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Chapter 1. Introducing the IBM 5110 


ABOUT THIS MANUAL 


This manual will show you how to operate the IBM 5110 using the APL 
language. If you are not familiar with the APL language, you should do 
the suggested keying operations or examples on your 5110 while reading 
the manual from cover to cover. If you are familiar with the APL 
language, you should read Chapters 1 and 2 to learn how to operate the 
5110; however, you may then want to skip to Chapter 7. Not all of the 
features or functions of the APL language are covered in this manual. 
For more information about the 5110 or the APL language, see the /BM/ 
5110 APL User’s Guide, SA21-9302, or the /BM 5110 APL Reference 
Manual, SA21-9303. 


This manual was written with the assumption that the 5110 has been 
set up and checked out. If the 5110 has not been set up, use the setup 
procedure in the /BM 5770 Setup Procedure, SA21-9318, before 
continuing to read this manual. 


ABOUT THE APL LANGUAGE 


APL has many built-in functions that allow you to effectively solve your 
problems. However, if you need a special function to solve a problem, 
APL also allows you to define your own functions. The functions you 
define are similar to programs written in other computer languages. 


APL is a good language to experiment with; nothing you do from the 
keyboard can damage the 5110, and the more you experiment, the more 
you will learn about APL. 


ABOUT THE SYSTEM 


The IBM 5110 Model 1 (Figure 1) is a computer designed to help you 
solve problems. The IBM 5110 Model 2 differs from the Model 1 in 
that the Model 2 does not have a built-in tape unit. The display screen 
and indicator lights communicate information to you, and the 
keyboard and switches allow you to control the operations the system 
will perform. 


Before you begin to use the 5110, you should become familiar with the 
keys and control panel. The control panel switches will be discussed 
later. Following is a brief description of the keys (Figure 2); how you 
use the keys will be discussed later. 
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Alphameric Keys 


The alpha keys are similar to those on a standard typewriter, except that 
there are no lowercase characters. In standard APL character mode, the 
alpha characters are all uppercase, even though they are in the lowercase 
position on the keys. Thus, you do not use the shift key for 

alpha characters. 


If you want to enter an upper shift character, you must hold down the 
shift key and then press the key to enter the character, just as you 
would to type an uppercase character on an ordinary typewriter. 


You can also enter lowercase alphabetic characters from the keyboard. 
How you enter lowercase alphabetic characters is discussed later in this 
chapter. 


Numeric Keys 


Either the top row of alphameric keys or the special calculator arrange- 
ment of numeric keys can be used to enter numbers. 


Operating Keys 


The black key labeled EXECUTE, the dark gray keys with the legend 
names CMD, ATTN, and HOLD, and the dark gray keys with the arrows 

_are all special operating keys. The keys with the arrows and the space- 
bar, which is used to enter blank characters, automatically repeat the 
operation they perform when held down. 


Backspace Key 
Forward Space Key 
Attention Key 


Scroll Up Key 


Scroll Down Key 


Hold Key 


Execute Key 


REVERSE 
IN PROCESS DISPLAY RESTART 
Indicator Switch Switch 


BASIC/APL DISPLAY 
Switch REGISTERS/NORMAL 
Switch 


PROCESS 
CHECK Indicator 


Error 
Message 
List 


Brightness (39 64 R32 
Control. Switch 


POWER \ 
ON/OFF 


Switch 
Display Tape 
Screen Cartridge 


(Model 1 only) 


Arithmetic 
Function 


Alphameric 
Keys 


eT ya Numeric Keys 


EXECUTE Key 


Shift Key 


Figure 1. The 5110 Computer 


Introducing the IBM 5110 3 


APL System Command Keywords 


The words that are above the top row of numeric keys are system command 
keywords, which you can enter by holding down the CMD key and then 
pressing the key below the desired keyword. For example, to enter 
)LOAD, hold down CMD and press the 1 key. The system commands 

and their uses are discussed later, in Chapter 9. 


Also, notice the special character combinations engraved on the front of 
the alphabetic keys. If you have a combined APL/BASIC machine, there 
is also a BASIC statement keyword engraved above the special character 
combination on the front of the key. You can enter the special charac- 
ter combination by holding down the CMD key and then pressing the 
appropriate key. You will see how these special character combinations 
are used as you become familiar with the APL language. 


BASIC Statement Keyword 


APL Special Character Combination 


Arithmetic Function Keys 


The four keys to the right of the calculator arrangement of numeric keys 
are the arithmetic function keys. These keys are used to perform division, 
multiplication, subtraction, and addition. There are also keys on the 
alphameric keyboard that perform these functions. Notice that the + and 
x symbols are used for division and multiplication. 


GETTING STARTED 


Make sure the switches on your |BM 5110 are set as follows: 


Switch Setting 
L32 64 R32 (5110 only) 64 
BASIC/APL (combined machines only) APL 
DISPLAY REGISTER/NORMAL NORMAL 


If your 5110 has the BASIC/APL switch, it can execute both BASIC and 
APL language statements. The language to be used is selected by the user 
before power up or during the restart sequence. 


Make sure your 5110 is plugged in and turn power on. If power is 
already on, press RESTART and wait about 20 seconds. During this 
time, the 5110 performs internal checks to make sure it is operating 
correctly. 


After 30 seconds, if the message CLEAR WS has not appeared in the 
lower left corner of the display screen, an error has been detected during 
the internal checks. In this case, press RESTART. The 5110 will per- 
form the internal checks again. If the CLEAR WS message does not 
appear after several tries, call your service representative. 
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Figure 2. The Keyboard 
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Special Operating Keys 


COPY 


Numeric Keys 


Alphameric Keys 


ENTERING AND DISPLAYING DATA 


First, let’s look at the display screen. Normally, information displayed 
by APL begins at the left edge of the display screen, and the input from 
the keyboard is indented when it is displayed. The small horizontal 
flashing line indicates the position on the line where the next input from 
the keyboard will be displayed. This flashing line is called the cursor. 
The cursor moves as each character is displayed. 


The display screen can contain up to 16 lines of data. Each line has 64 
positions across the display screen. The bottom two lines are used to 
display input, and the remaining 14 lines contain a history of the opera- 
tions you have performed. 


Line ———_ 64 Character Positions ——_-_->- 


Numbers 

15 

14 

13 

12 

11 

10 
9 
8 
7 
6 
> This message is displayed when your 5110 
4 is ready for use. 
3 
2 CLEAR WS Cursor (flashing line)—display of keyboard 
1 bis ee input normally begins indented six positions 
0 on line 1. 


There are 128 positions available for input from the keyboard; that is, 
there are 64 positions available on line 1 and 64 positions on line 0. When 
position 64 of line 1 is used as you enter data from the keyboard, the 
cursor moves to the left margin of line O. The cursor is then at position 
65 of the possible 128 positions available for input. 
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Now let’s enter some data into the 5110 using the numeric keyboard 
and the arithmetic function keys. Press the following keys: 


Notice that the characters are displayed as each key is pressed. To 
process the data you just keyed, you must press the EXECUTE key. 
Press the EXECUTE key now. 


The display screen will look like this: 


CLEAR WS 


mths 


Notice that the expression you entered, 2+3, appears indented on the 
display screen; the answer, 5, appears on the left margin of the next line; 
and the cursor appears on the next line. The information displayed 
moves up each time the EXECUTE key is pressed. 


Enter and execute the expression 125+75 by pressing the following keys: 


SiS alae 


The display screen will look like this: 


The appearance of your display can be changed by the REVERSE 
DISPLAY and L32 64 R32 switches on the control panel. The 
REVERSE DISPLAY switch allows you to change from black characters 
on a white background to white characters on a black background and 
vice versa. Change the switch and select the type of display you feel 
most comfortable with. You may have to adjust the brightness control 
as you change from one to the other. 


Now, watch the display as you set the L32 64 R32 switch to the L32 
position. With the switch in this position, the leftmost 32 characters on 
each line are displayed with an extra space between each character. The 
rightmost 32 characters on each line will not be displayed. With the 
switch in the L32 position, your display should look like this: 


In the R32 position, the rightmost 32 characters are displayed with a 
space between each character. Now, set the switch in the R32 position 
and notice that the display is blank because there were no characters in 
the rightmost 32 positions of the display screen. 


Return the switch to the 64 position, and notice that all characters are 
displayed without the space in between. For exercises in the remainder 
of this book, keep the switch in the 64 position. 


There are two keys above the numeric keys that move the display line 
up or down. The up arrow {@_ (scroll up key) moves the display up 


one line and the down arrow (scroll down key) moves the display 


information on any line that is moved off the display screen is lost. Also, 
the cursor returns to position 7 on line 1 when either scroll key is used. 
Either key continues to move the display lines if it is held down. Now 
use the down arrow to move the display down one line. 


The display will look like this: 


CLEAR Wis 
aes 


The value 200 is now on the input line and 
can be used as input. Notice that input can 
begin in any position on the line. 
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Now press the following keys: 


(i) Ce) 


The display screen will look like this: 


CLEAR WS 
aed 


Late 
200 +50 


ut 


Now that you are familiar with the display screen, only the line or lines 
being discussed will be shown. 


CORRECTING KEYING ERRORS 
The IBM 5110 has a number of very useful features that allow you to 
correct errors made when data was entered. On a line-by-line basis, at 
any time, you can: 
e Replace a character 


e Delete a character 


e Insert a character 


Replacing a Character 


To replace a character, move the cursor with the backspace key 


or forward space key, until the cursor is positioned at the 
incorrect character. The cursor moves one character space in the 
direction of the arrow each time the appropriate key is pressed. These 
keys continue to move the cursor if they are held down. When the cursor 
is at the incorrect character, you replace the incorrect character by 
simply keying the correct character. 


For example, you want to do the problem 22+12. But you press the 
following keys: 


(J 
The display screen looks like this: 
To correct the error, the cursor must be moved back one position (under 


the second 1) so that the character can be rekeyed. Now press the 
backspace key one time. Note that the cursor is replaced by a 


flashing character. The flashing character serves the same function as the 
cursor; it indicates the position on the line where the next input from the 
keyboard will be displayed. Now to correct the error and execute the 
problem, press the following keys: 


Deleting a Character 


To delete a character, you also use the backspace key or forward 


space key § to move the cursor. Once the cursor is in the position 


of the character to be deleted (the character is flashing), hold down the 
CMD key and press the backspace key once. The character is then deleted 
and any characters to the right are shifted one position to the left to 

close up the space left by the deletion. 
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For example, you want to do the problem 13+45. But you press the 
following keys: 


(:} 
The display screen looks like this: 


Leseus 


Press the backspace key and move the cursor (flashing character) back 

to the 2. Look at the labels that appear above the backspace and 

forward space keys: DELETE and INSERT. To delete the 2, hold down the 
CMD key while you press once. 


The display screen looks like this: 


Lathes 


This character is flashing. 


Now press the EXECUTE key to execute the problem. 


Inserting a Character 


To insert a character, position the cursor using the backspace key 


or forward space key; then hold down the CMD key and press 


the forward space key once. This operation moves the flashing 
character (and all other characters to the right of it) one position to the 
right, creating the space you need to insert one character. The cursor is 
not moved. Now, to insert the character, simply press the desired key. 


For example, you want to do the problem 123x6. But you press the 
following keys: 


LJ L+} 
The display screen looks like this: 


13%6.. 


To correct the error, press the backspace key and move the cursor 

(flashing character) back to the 3. Look at the labels that appear above 

the backspace and forward space keys: DELETE and INSERT. To perform 
the insert function, with the cursor positioned at the 3, hold down the 

CMD key while you press once. 


The display screen looks like this: 


13 KS 


Now to correct the keying error and execute the problem, press the 
following keys: 
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There is one more way to correct a keying error. If you make several 
errors part way through the line, you can backspace the cursor to the 
character following the last correct character and then press the ATTN 
(attention) key. Everything from the cursor position to the end of the 
input line will be cleared from the display. 


Since the data from the input line is not processed until the EXECUTE 
key is pressed, you can visually verify any input before it is processed. 
However, if you do press the EXECUTE key before you notice a 
mistake, you can simply enter the input again or you can use the down 
arrow § (scroll down key) to move the input back down to the 


input line to correct it. Either way, you must press the EXECUTE key 
again. 


For example, you want to do the problem 135+280, but you enter and 
execute 134+280. The display screen looks like this: 


13442360 
Ly. 1. 


To correct the input, press the down arrow three times to clear 


the result from the screen. The display screen now looks like this: 


Then press the up arrow once to move the original input back 


up to the first input line so that it can be corrected. 


ENTERING LOWERCASE ALPHABETIC CHARACTERS 


Although only the standard APL alphabetic characters are shown on 
the 5110 keyboard, you can enter Jowercase alphabetic characters by 
changing the 5110 to lowercase character mode. One way to change 
the 5110 to lowercase character mode is to press the neko key (the 


characters HOLD are displayed in the lower left corner) and then hold 
down the shift key and press the scroll down key. The 


5110 is now in lowercase character mode. For example, press the 
key. The display screen looks like this: 
A 


a 


Now, hold down the shift | 


key and press the key. The 


display screen looks like this: 
a AL 


Finally, hold down the command 


key and press the key. 


The display screen looks like this: 


AAO 


In this example, you are not going to execute the data just entered from 
ane ceypoald because you will get an error. Instead, press the scroll up 
[ae key once to remove the data from the input line. Now, to 


key and then hold down the shif key and press the scroll up 


key. The 5110 is now in standard APL character mode. 


Note: See Console Control in the /BM 5110 APL User’s Guide, 
SA21-9302, for more information on how to enter lowercase characters. 
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From this point on, we will discuss the APL language and use examples 
in the following format to illustrate what we are discussing. You enter 
the expressions that are indented. The results displayed on your 5110 
should be the same as the results shown in this manual. 


EXAMPLES: 


3 -+ 14. ~————-. Expressions To Be Entered 


7 eee 
Results 


Remember, the data you key is not processed until 
the EXECUTE key is pressed. 
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TYPES OF FUNCTIONS IN APL 


There are two types of functions in APL: user-defined functions 
(programs) and those that are built into the APL language. The APL 
built-in functions are denoted by special symbols. User-defined 
functions are discussed later, in Chapter 7. 


The built-in functions operate on data supplied, called arguments. 
For example: 


3 
Right Argument 


a’ 


uilt-in Function (addition) 


Left Argument 


ADDITION, SUBTRACTION, MULTIPLICATION, AND DIVISION 


x a Machines with APL Only 
ar. 
+ x 
Combined Machines 


Alphameric Keys Arithmetic Function Keys 


Four commonly used built-in functions (+ - x +) perform the normal 
arithmetic operations when they are used. These symbols are located 
on the top row of the alphameric keys and also to the right of the 
numeric keys. 
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EXAMPLES: 


3th Add 3 and 6. 
AXG Multiply 3 times 6. 
3 
+o a 
iy. > The right argument is subtracted from the left argument. 
eH 


Me ON The high horizontal bar is the negative sign. Compare it 
with the minus which is the symbol for subtraction; the 
negative sign appears near the top of the character instead 
of on the center line. 


ht Uy 
ie ee The left argument is divided by the right argument. 


As you have seen in the example, the negative sign is different from the 

minus. When you are doing arithmetic operations in APL, do not use 

the minus to represent negative numbers or the negative sign for 
2 


a subtract operation. 


Problems: Using Addition, Subtraction, Multiplication, and Division 


1. Find the total number of cars that a dealer sold during one week if 
his daily sales were 3, 5, 2, 6, 7, 3 and 4. 


2. Find the net number of cars removed from the same dealer’s lot if 
20 people had trade-ins. 


3. Find the dealer’s average profit per car if he made a total profit of 
$2700 for the sales in problem 1. 


4. Find the dealer’s total earnings if he made $20 on each car sold. 


Possible Solutions 


Problem 7: 


Behe eG 74 Sth 


Problem 3: 


oe UO 30 
ant 
Problem 4: 

2x SG 


600 


ANOTHER ARITHMETIC FUNCTION—RAISING A NUMBER 
TO A POWER 
ee 


Another arithmetic function that you are probably familiar with is 
raising a number to a power. In APL, you use the « function to raise 
the left argument to the power specified by the right argument. 


EXAMPLES: 


a. 
< 


2 %3 «———— 2 raised to the third power. 
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Finding the Root of a Number 
You can use the power function x to find the root of anumber. To do 


this, you simply raise the number to the power 1+n, where n is the root 
you want to find. 


EXAMPLES: 


1.9 C+) +————— The square root of 4. 


Wwe 


Another way to enter the instruction to find a 
square root of a number (.5 is the same as 1=2). 
GMC 123) 

The cube root of 8. 


STORING DATA IN THE 5110 FOR LATER USE 


You can store data, either direct input that you enter from the keyboard 
or the result of a calculation. These stored items are called variables. 
Each variable has a name associated with it. Whenever you use the name of a 
variable, APL supplies the value associated with that name. A variable 
name can be up to 77 characters long (with no blanks); the first 
character must be alphabetic; the remaining characters can be any 
combination of alphabetic and numeric characters. It is good practice 
to use names that represent the data you are storing. For example, if 
you want to store a value that is the area of a rectangle you might use 
the name AREA; or if you want to store some sales data, you might use 
the name SALES. 


You create a variable by assigning the data to a name. To assign a value 
to a name, you use the assignment arrow «. The value to the right of 
the « is assigned to the name to the left of the <. 


EXAMPLES: 


PRICE¢99 ,350— After you press the EXECUTE key, you 


SALES+¢ PRICE x10 have created a variable named PRICE 
Ne a secre 
PRICE * with a value of 99.50. 
lag eo) te 
a re 
a ne . 
SALES The result of a calculation can also be 
99S assigned to a variable. 
If you want to know the current value of 
a variable, you simply enter the name of 


the variable. 


PRICE¢&6,. 75 


You can change the value of a variable 


PRICE the same way you assigned the original 
84.75 ; value. 

PRICE¢ PRICE+10 

PROT CHE You can also use the variable and change 
96.7% its value in the same instruction. 

You cannot use a name as a variable if 
ee it does not have a value assigned to it. 

COSTE SALES 
VALUE ERROR -——— The error message indicates why the 

COSTtSAaALes instruction failed. 


ee The caret (A) indicates where the 


t instruction failed. 


Note: Do not be concerned at this time 
about the error message that is displayed; 
all of the 5110 APL error messages and 
suggested user’s responses are described 
in the /BM 5110 APL Reference Manual, 
S$A21-9303. 


PERFORMING SEVERAL FUNCTIONS IN THE SAME EXPRESSION 


In the preceding examples, only one arithmetic function was used in 
each example. However, you are not restricted to writing expressions 
with only one function. Any number of functions can occur in the 
same instruction. As soon as you use more than one function, however, 
you must be concerned about the order in which they are used. /n APL, 
the rightmost function in any expression is executed first, then the next 
rightmost, and so on. 
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EXAMPLES: 


Order of execution is right to left. 


‘%x 3414, «—— 4 is added to 2, and that result is multiplied by 3. 


18 
4 3x «———>_- is multiplied by 2, and that result is added to 4. 


10 


Remember that an APL function uses as its right 
argument the result of the expression to its right. 


SPECIFYING THE ORDER OF EXECUTION—USING PARENTHESES 


In APL, parentheses are used the same way as they are in conventional 
arithmetic: the expressions inside the parentheses are executed before 
the expressions immediately outside them. 


EXAMPLES: 


(4x 39+. ~—— The expression 3x2 is evaluated first and the 
1.0 result is added to 4. 


CU4F3 KO 
bi The expression 4+3 is evaluated first and the 


Ly 
result is multiplied by 2. 


Remember, the rule of the order of execution 
is from right to left with the expressions in 
parentheses resolved first and from right to 
left as they are encountered. 


USING STRINGS OF NUMBERS AND TABLES 


A powerful feature of APL is the way it handles strings and tables of data. 
So far, you have used APL with only single numbers (called scalars): but 
APL also works with strings of numbers (vectors) and tables (matrices). 
The functions you have performed using single numbers are simply 
extended to each number in a string or a table. For example, if you have 
a string of numbers assigned to a variable named SALES, you can add 2 
to each number in the string by simply entering 2+SALES. 


Using APL with Strings of Numbers (Vectors) 
A string of numbers is called a vector. When you enter a string of numbers, 


there must be at least one blank between each number; each number is 
called an e/ement of the vector. 


EXAMPLES: 


1 Wu? FY 35 You have entered a five-element 


1 uu 3B GS BS vector (a string of five numbers). 
STRINGeE LUG 146 39 2 
STRING A vector can be assigned to a 
L444 16 3&9 & variable name. 


SALESe¢ LSS 220 S16 Fo 
SALES * 10 ——-ec— Each element (number) in the 
L250 2200 3140 900 vector can be operated on by 
a single number. 


SALES ——————————— Note that the value of SALES 


L25 220 S16 70 has not changed. 

PRICE¢ 50 1.00 .75 1.40 

TOTALe¢ SALES *PRICE 

TOTAL Each element in a vector can be 
62.5 220 227 oF operated on by the 


corresponding element in 
another vector with the same 
number of elements. 


LoS Wet SG 
~ f LU —— There must be at least one 
Lees blank between the elements 


Sou of the vector, or the result 
will be different. 


Lo of 3+) &-_——————— _ You cannot use two vectors 


LENGTH ERROR that do not have the same 
12? 3+ & number of elements unless 
A one of the arguments is a 


single number (single element). 
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Problems: Using Strings of Numbers 
1. Find the squares of the numbers from 1 to 5. 
2. Find the squares, cubes, and fourth powers of the numbers 2 and 3. 


3. Asmall mutual fund broker specializes in five funds. He wants to 
know how much of each fund he had sold at the close of the day. 
By 4:00 PM, he had sold $1500, $3200, $1200, $2300, and $2400, 
respectively, of the five funds. In the last hour of the day, he sold 
$100, $500, $300, $200 and $0 of the respective funds. Write a 
single APL statement to determine his closing sales figures for each 
fund. 


4. The five funds in problem 3 sold for $7.30, $11.58, $3.45, $2.17 
and $5.56 per share. How many shares of each fund were sold? 


5. The broker receives the following percentages of commission on the 


five funds: 3.25, 2.5, 3.0, 3.75 and 3.5. How much did he earn 
from each fund today? What are his total earnings for the day? 


Possible Solutions 


Problem 1: 
1 2 AY Se 
1 \y ‘? 1. & : % 
Problem 2: 
~ A It } 
YY 
2 RS 
Q 07 
2 Rae u, 
14 St 
or 
eed FY 
y 8B Le 


Problem 3: 


L500 S200 1200 2300 2400+100 
1600 3700 1500 2500 2400 


Problem 4: 


L600 S700 1500 2500 240027. 30 
el¥.18 S19.52 454.78 1AS2.1 434.465 


Problem 5: 


Loou S700 1500 2500 2600x, 0325 


ve 92.5 45 93.75 84 


Using APL with Tables of Numbers (Matrices) 


OU 


300 


0250 


200 0 


0300 


A table of numbers is sometimes called a matrix. The numbers in the 


matrix are arranged in rows and columns; each number is called an 


element of the matrix. 


f-Column 


[ese An individual element in row 3, 


column 4 of the matrix. 


You can use the reshape p function to create matrices. The left argu- 
ment specifies the number of rows and columns, and the right argument 
specifies the data or variable name for the data to be placed in the matrix. 


(ORES 
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EXAMPLES: 


The first number in the left argument 
specifies the number of rows; the second 
number specifies the number of columns. 
2? Sel 2 34 S 6 
5 ame eee eee eee y 67 right argument specifies the values to 
yw 8 4 be placed element by element into the 
rows of the matrix. 


There must be a blank between the 
numbers specifying rows and columns. 
TABLE¢? Sel 2 3 


TABLE 
oo 3 ____—— If there are not enough elements in the 
yt 2 right argument to fill the matrix, the 


elements are repeated. 


VECTOReL 2 3 4 5 6 7 BF 10 11 te 
iM A q : pl 3 SeVECTOR lf there are more elements in the right 
PRE Me Po argument than are required to fill the 


iF “ 3 matrix, only the first (leftmost) elements 
hoa are used. 
789 
The reshape p function can also be used 
to create a vector. 
FOURGH PYEC TOR 
| : OUR The number of elements in the vector. 
12 3 4 
MA v RY rf +10 Each element in the matrix can be operated 
lio dea 13 on by a single number (remember, the 
LY TS 16 value of MATRIX is not changed). 
17 18 19 
NUMBERS¢e1 2 3 4 3 6 7 BY? 
EXAMPLES¢3 SeNUMBERS +S Remember that APL executes an 
EXAMPLES expression from right to left—the 
» ¢ & result of NUMBERS+5 is used as 
? 1 ) Li. the right argument for the reshape 
12643 14 p function. 


RESULTS¢ EXAMPLES +MATRIX 


RESULTS 
rar es 
i 2a 1 Each element in a matrix can be operated 


Moe cages ae ; 
; = : : z a on by the corresponding element in another 
LY 21 23 matrix of the same shape. 


EXAMPLES—continued 


Se2 B2eNUMBERS 
5 . 


MATRIX XNUMBERS 
RANK ERROR 
MATRIX *XNUMBERS or 


fs 


A matrix and a vector 


MATRIXXLESS ——————- two matrices that do not have 


LENGTH ERROR the same shape (number of rows 
MATRIXXLESS and columns) cannot be used 
A unless one of the arguments is 


a single number. 


REFERRING ONLY TO CERTAIN NUMBERS IN A STRING OR TABLE 
OF NUMBERS (INDEXING) 
. ; { | 


Indexing is a way to refer to only certain elements in a string or table 
by specifying the position of the element you want. The numbers you 
use to specify the positions of the elements are called index numbers. 
These index numbers are enclosed in brackets [ ] following the vector 
or matrix to which they apply. 


EXAMPLES: 


TEMPE SO 7H 76 65 80 BOS FS 
TEMPS ee" You can refer to a single 
ra element. 
TEMPS 1 2a 
oo Vu ————_$_______________ You can refer to several 
. elements. Notice that the 
elements are displayed in 
the order in which you 
indexed them. 
TEMPS I+TEMPES do 22 
LSe AHS Tas You can index and use 
other functions in the 
same expression. 


TEMPE #¢88 You can change a single 
TEMP element of a vector. 
46 7H YB 65 80 8S 86 
TEMPES 6. c0 
TEMPES 62 aa eee can also change several 
70 70 elements. 
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EXAMPLES—continued 


TEMPLES bide 32 36 
oo 


TEMP ae Notice that the new values 
86 74h 70 65 32 70 B88 are assigned in the same order 
as the index numbers. 


For a matrix, you need 

an index number for the 
rows and an index number 
for the columns—these 
numbers are separated 

by a semicolon. 


TIMES¢3 3S eNUMBERS ——— Remember, we have previously 
TIMES assigned a value to NUMBERS. 


Left side of the ; specifies 
the row(s). 


- Right side of the ; specifies 
the column(s). 


— You can refer to a single 
element 


TIMEST2 5 2. or 


TIMESES;2 31 ———______ you can refer to several 


“oY elements. In this case, you 
TIMESE1, 1 23 have referred to the second 

1 2 and third elements in the 
TIMESE 2 3)2 33 third row. 


ane 

G9 Sn ae Be : 

‘ — Notice that when you refer 
to more than one row and 
more than one column, your 
result is a matrix. 


EXAMPLES—continued 


SS If you do not specify a 
TIMESE2 5 2 column, you get the whole 
Yo } row. 
TIMESE: 33 
3.64 ¢ If you do not specify a row, 


you get the whole column. 


These values (the third 
column) are displayed 
horizontally, because they 
are a string of numbers 

y (vector). 


TIMES; 1 30) 


Note: Even when you select 
entire rows or columns, the 
semicolon is still required to 
make it clear whether the 
index number is for the rows 
or columns. 


TIMES 2; Lx TIMESE ; 3+ You can index and use 
4e other functions in the 


TIME StS; 22¢0 same expression. 
Le 3 You can change the value of 


elements in a matrix. 
if BY 

TIMESEL; Lde 243 
TIME SUL; 12 


YOU ARE NOT LIMITED TO USING ONLY NUMBERS 
K 


Although the examples so far have used only numeric data, APL also 
works with character data. Character data, for example, can be used 

for headings on a table or to create a list of names. When you enter 
character data, you must enclose the data in single quote characters ('). 
These single quote characters indicate that the data is character data and 
is not a variable name, a number, or a function. When character data is 
displayed, the single quote marks do not appear. 


Character data, like numeric data, can be a single character (scalar), a 
string of characters (vector), or a table of characters (matrix). Unlike 
numeric data, when you have a character vector or matrix, each character 
is a separate element and is not separated from the other elements by a 
blank. In fact, a blank in the character data is also a character (blank 
character). 
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EXAMPLES: 


NE Single character 
A (scalar). 

“ARC ee 
ARC —————_ String of three 


ee: characters (three- 


ie. This expression does 

not yield a result of 
5, because the values 
are characters, not 
numbers. 

NUMGBERE HSS 

"223 ' + NUMBER 

HOMATIN ERROR You cannot add 
“123° + NUMBER character data and 
A numeric data. 


. To place a quote within 
‘NON’ CT 20 THAT the character string, 
CON’ Y 20 THAT you must use a pair 


THANKS YOU ARE WELCOME‘ of quotes. 
THANKS Se 
YOU ARE WELCOME Character data can be 


assigned to a variable 
name. 


Blank characters. 


NAME S¢ ‘SAM JOHNJACK TOM 


MATRIXNG 4 & eNAMES ~———————— Create a character 
MATRIX matrix, each row 
SAM represents a name. 
JOHN 
JACK 
TOM 


NAMESES & 7 Bd 
AGH j ee 

MATRIXAT 2p ————— Indexing works with 
JOHN character data also. 


So far, you have used APL with some common arithmetic functions. 
You have also seen how APL works with scalars (single data items), 
vectors (strings of data), and matrices (tables of data). However, you 
are not limited to just the functions we have discussed so far. In the 
following chapters, you will be introduced to more things you can do 
with APL. 


Chapter 3. APL Functions That Require One Argument 


In this chapter you will use some APL functions to do the following: 
e Determine the whole numbers nearest a fraction. 

e Sort a vector into ascending or descending order. 

e Generate a random number. 

e Find the shape of an existing variable. 


There are additional APL functions that require one argument; however, 
these functions will be discussed later, in Chapter 6. 


HOW MANY ARGUMENTS ARE REQUIRED BY AN APL BUILT-IN 
FUNCTION? 


In this chapter, you will use APL functions with one argument. In the 
next chapter, you will use some of the same APL function symbols with 
two arguments. As you will see, these symbols perform different APL 
functions when they are used with one and with two arguments. When 
you use an APL function with one argument, the argument must be to the 
right of the function symbol. 


APL FUNCTION SYMBOLS THAT ARE A COMBINATION OF TWO 
CHARACTERS 


Some of the APL function symbols you will use are a combination of 

two characters. You remember that when correcting keying errors, if 

you positioned the cursor at a certain character and pressed another key, 

a new character would replace the original character. However, certain 
APL symbols require two characters, one struck over the other. For 

these symbols, key the first character, backspace, and key the second 
character. It does not matter in which order the characters are keyed. 

The symbols that are a combination of two characters are called overstruck 
characters. Appendix A shows the overstruck characters and the keys 
required to enter them. 


Note: \|f you key an overstruck character and then want to change it, you 


can position the cursor at the character and key another character. The 
new character will replace the overstruck character. 
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DETERMINING THE WHOLE NUMBERS NEAREST A FRACTION 


When you want to disregard the fractional part of a number and just 
consider the nearest whole number, you can use the floor | and ceiling [ 
functions. The floor function will round the number down to the next 
smaller whole number and the ceiling function will round the number up 
to the next larger whole number. 


EXAMPLES: 


he 3, S29 


Lo 


Li 


result is the same as the argument. 


a the number is already a whole number, the 
“x 
ad 


yt The result for the floor and ceiling functions is 
oe: determined according to the number’s position 
on the number line: 


(smaller) (larger) 


SHH HHH 


432101234 


Rounding to the Nearest Whole Number 


It is acommon practice to round numbers to the nearest whole number. 
You can do this by adding .5 to the number and then using the floor 


function. 
EXAMPLES: 
Xe, U+ , 3+———————-. Rounds 4.4 to the nearest whole number. 
|X 
th 
' ; G+, 5+ Rounds 4.6 to the nearest whole number. 
A 
a 
, Xeue bee 


Pe ' rad 
hy. ; 
€ : a These examples could also be entered this way. 
Xe Lu. Gr. oS 
va 
A 


SORTING A VECTOR IN ASCENDING OR DESCENDING SEQUENCE 
b | - 
LJ 


The grade up 4 and the grade down Y functions can be used to sort a 
numeric vector into ascending or descending sequence, because they 
give you the indices of the argument in ascending or descending order. 


EXAMPLES: 


ACBO US S62 37 29 Cu SE LS 86 


AA of eee largest value.is the ninth 
= f 3 6&6 1 Y 


element. 


The smallest value is the 
eighth element. 


Real dad 


Indexing A this way sorts the 
i elements of A in ascending 
1S 29 37 4S SB 62 74 BO 96 order. 


Remember, when indexing 
elements in a vector, the 
index numbers or the 
index expression must be 
enclosed in [ ]. 


A 
Y9 1. & 3 FY Bu S & 
© AL PA o] -——————_—__——_—_—_____ The elements of A are sorted 
(c 


in descending order. 
74 BO 74 62 SSG US BS? Be 1s 
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GENERATING A RANDOM NUMBER 
a) 


To generate a random number, you can use the roll function ?, which 
generates a random number between 1 and the value of the argument. 


EXAMPLES: 


Xe? & + Generates a number between 1 and 6. 


Vv 


x 
The result can be any number between 1 and 6. 


Se 


Ke?G& & 4& G ee 
Xx When this function is used with a vector, a 
ae ae ae random number is generated for each element. 


GENERATING CONSECUTIVE NUMBERS | 2 
] 


There are times when you will want to generate a vector of consecutive 
numbers from one value to another value. You can do this by entering 
an instruction like this: 


VECTORe 1 2 3 4 a 6 ¥ GB 
VECTOR 
Le 34 5 6 7 8 


However, you can also use the index generator function ;,, which generates 
consecutive numbers from 1 to the value specified by the argument. 


EXAMPLES: 


ig ie Eight consecutive numbers 
me? e 


: oF nm é 2 ¢ 
| 23464 S&S 6&6 #7 & 
VEC TUR S-+ )  ———— Five added to each consecutive number 
VECTOR 
6 7 8 FY Lo 
2k. ——————___—_—__ First 6 powers of 2 
2 YY 8 16 Be GY 


Generating an Empty Vector 


An empty vector is just that—a vector with nothing in it (no elements). 
Why have a vector with nothing in it? As you will see later, when joining 
two items together or branching in a user-defined function, there are 
times when you will want to generate an empty vector. One way to 
generate an empty vector is to use 10. 


EXAMPLES: 


NAME. 
VALUE ERROR An error occurs if you use a variable name that does 
NAME not have a value assigned. 


f ~ 


NAME 7 —_— Generate an empty vector. 
NAME 
The result is a blank display line (no value). 


FINDING THE SHAPE OF AN EXISTING VARIABLE 
R 


As you learned in Chapter 2, the left argument of the reshape function 
determined the number of elements in a vector or the number of rows 
and columns in a matrix. Thus, the number of elements in a vector or 

a matrix is referred to as the shape of the vector or matrix. For example, 
the shape of matrix M, which has two rows and three columns, is: 2 3. 
To find the shape of an existing variable, you can use the shape function 
@) . 


EXAMPLES: 


SS CHAL eRe 
VEETORe 2 & & & 
MATRIX: 3p io Reshape function (has two arguments). 


—  ——— Blank display line—the shape of a scalar 
eV¥VEC TOR is an empty vector. 


eMaTR EX Number of elements in the vector. 


2 Be 


EMPTY «©. U————_ Generates an empty vector. 
EMPTY 

Blank display line. 
PEMP TY 


gy. —<—$ —_______________________ Number of elements in an empty vector. 


Number of rows and columns in the matrix. 
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In this chapter you will use some APL functions that require two 
arguments. You can use these functions to do the following: 


e Compare the arguments to determine whether one is equal to, greater 
than, or less than the other argument. 


e Process logical data—true (1's) and false (O's) data. 

e Find the larger of two numbers. 

e Find the smaller of two numbers. 

e Find the index of a value in a vector. 

e Generate a random sequence of numbers. 

e Compress (select certain elements from) a vector or matrix. 
e Expand a vector or matrix by inserting zeros or blanks. 

e Join two items together. 

e Find the logarithm of a number. 


There are additional APL functions that require two arguments; however, 
these functions will be discussed later, in Chapter 6. 


RELATIONAL FUNCTIONS 
When solving problems with APL, you might want to test the relationship 
between two values. For example, you might want to test a counter to 
see if it has reached a certain value; or you might want to do something 
different in the solution to your problem, depending on whether a certain 


condition is true or false. The following APL functions are used to test 
the relationship between two values: 


Function Symbol Key 


Greater than > 


Less than < 


Greater than or equal to 


IV 


Less than or equal to < 
Equal to = 
Not equal to z 


When these functions are used, the relationship between the two values 
is evaluated, and a 1 results if the relationship is true, anda 0 if false. 
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EXAMPLES: 


Ae 10 
Ke 20 
Ah 
0 
A=B- 10 
L 
AEE 
1 
Ax kt 
‘1. 
ALE 
0 
At ABC ' 
Be THER ' 
AZ 
au 0 a. 
Axe 
-de 


The = and # functions also work with character 
data. Remember, each element is compared with 
the corresponding elernent in the other argument. 


Why Two Numbers Identical in Appearance Are Not Always Equal 


APL stores all numeric values with an internal precision of 16 decimal 
digits; however, decimal! values with more than five significant digits are 
normally rounded off to five digits before they are displayed. Thus, 
occasionally, different numbers will look alike when displayed. 


EXAMPLES: 


At 123 
Re, 33333 
A 
0,33333 
i 
0.33333 


A= fy «H+ The values are not equal. 


Only five of the 15 digits are displayed. 


0 


PP ———————_ [PP is a system variable that determines how 
many significant digits will be displayed. This 
variable is automatically set to 5 when the 
power is turned on or RESTART is pressed. 
(The system variables are discussed in 


ur 


Chapter 9.) 
[FP 1 -——————_ Set the []PP system variable so that 15 
A significant digits will be displayed. 
0, SSSSSSSSRRSERSS 
is 


0,333 33 Notice the difference between the two values. 


[1 fr Pp ¢- Ha Se . 
Set the []PP system variable back to 5. 


Remember, the value displayed may not be the exact value that the 5110 
has stored for the variable. 


An Example Using a Relational Function 


Suppose the correct answer to a problem has been stored as a variable 
called RIGHT, and the answer supplied by a student has been stored as 
a variable called ANSWER. To keep track of the student’s score, you 
want to add 1 to his score if his answer is the same as the right answer; 
otherwise, you want to leave his score unchanged. 
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If the student got the problem right, it is true that ANSWER=RIGHT. 
To add 1 to his score only if his answer is equal to the right answer, you 
could enter this instruction: 


SCORE<SCORE+ANSWE R=RIGHT 


Then the amount added to SCORE is 1 when the two values are equal 
and O when they are not equal. 


Suppose that instead of adding 1 when the student is right, you want to 
give some problems more weight than others. The weight of the current 
problem is stored under the variable WEIGHT. If the student gets the 
problem right, you want to add WEIGHT to his score; otherwise, you 
want to leave his score unchanged. You could enter this instruction: 


SCORE<SCORE+WEIGHTxXANSWE R=RIGHT 


If the student’s answer is equal to the right answer, then ANSWE R= 
RIGHT has the value 1, so the amount added is WEIGHT x 1. But if 
the answers are not equal, then the amount added is WEIGHT x O, 
which is 0. 


LOGICAL FUNCTIONS 


The logical functions take only ones and zeros as arguments and are used 
to check for certain conditions. (They usually check the results of 
relational functions.) The fundamental logical functions are: 


Function Symbol Key 


And A 


In our discussion of the logical functions, we will use tables like the 
following one to show the possible results of the logical functions: 


To use this table, simply find the value of the right argument on top of 
the table and the value of the left argument on the left side of the table. 
Then, follow the column represented by the right argument down and the 
row represented by the left argument across. Where they intersect is the 
result of the logical function when those values are supplied as arguments. 
For example, find out what the result of 1 ~ 0 is as follows: 


Follow the value of the right 
argument down. 


Follow the value 
of the left 
argument across. 


And A 
0 


They intersect here; thus, 
the result is 0. 


The And function is used to check for two conditions being true. 


For example, suppose you want to know when the items that cost more 
than $100.00 have a quantity less than 10. You could use the following 
instruction: 


(COST? LOO ACQUANTITY «£109 
ts The result is 1 when the 
quantity is less than 10. 


The result is 1 when the cost 


is greater than 100. 


Notice how the parentheses in this instruction specify the order of 
execution. 
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EXAMPLES: 


QUANTITY¢8 

COSTe 120 

(COST LO0IACQUANTITY< 103 
SY ge 

QUANTITY¢ 25 

CCOST:LOOACQUANTITY<£109 


Both conditions are true. 


i). 


At least one condition is 
not true. 


The Or function is used to check for at least one of two conditions being 
true. 


For example, suppose you want to know when either the inventory for a 
certain item is less than 10 or the orders for that item exceed the inventory. 
You could use the following instruction: 


CINVENTORY=10) + CORNERS? INVENTORY > 


= result is 1 when the orders 


are greater than the inventory. 


The result is 1 when the inventory 
is less than 10. 


EXAMPLES: 


INVENTORY¢ 15 

GORMERSe S 

CINVENTORY=10 4 CORDERS: INVENTORY) 
Og Both conditions 

ORMERSe 25 are falee: 

CINVENTORY = 10 Vv CORDERS: INVENTORY) 


i 
a At least one of 


the conditions 
is true. 


Problems: Using Relational and Logical Functions 


1. It is vital to build error checking into all space systems to prevent 
catastrophe. For example, two indicators checking one condition 
are commonplace. If either or both of the indicators show danger, 
action must be taken. 


Assume that the A indicator is over its limit at 1.3725 amperes and 
the B indicator is over its limit at 1.5365 amperes. Enter an 
expression that will result in a 1 when one or both indicators are 
outside their limits; the indicators read 1.3732 and 1.5362, 
respectively. 


2. Asurvey was conducted by the PTA in which the teacher and the 
parent of the child each evaluated ten of the child’s characteristics. 


One child’s teacher replied 1,0, 1, 1,0, 1,0, 0, 1, O to the questions 
dealing with his characteristics. His parent answered 1, 0, 0, 1, 0, 1, 
1, 0, 0, O. 


Show which questions the teacher and parent both replied to with 
al. 


Possible Solutions 


Problem 7: 


Problem 2: 


CvlO x1 O 1 1 0 1 0 0 TF Ont 0 0 1 0 Tt 1 0 0 0 
1o0oagdu4)6 046 0 0 0 0 
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FINDING THE LARGER OF TWO NUMBERS @ 
$ 


The result of the maximum [ function is the larger of the two arguments. 


EXAMPLES: 


AGS 
Bed 
Ay 


CExBOPAXA 


To see how you could use the maximum function, suppose you work for 

a department store. Each month the store calculates the amount charged 
and the amount paid by each customer. Your job is to find the difference 
between the total accumulated charges and the total accumulated payments 
for each customer. This difference is stored in a variable named BALDUE. 
The store also charges a service charge of 1.5% of the unpaid balance each 
month. You could find this charge with the following instruction: 


CHARGE¢ BALOUEX ., O15 


However, some of the customers have overpaid their bills. For them, 
BALDUE is a negative number and shows as a credit on their monthly 
statements. If you calculate the service charge by the instruction just 
shown, you will be paying them interest at a rate of 1.5%. Instead, the 
store prefers to calculate the service charge as 1.5% of the balance due 
or of 0, whichever is greater. To do this, you could use the following 
instruction: 


CHARGE, G1 5* 0P BALOUE 


FINDING THE SMALLER OF TWO NUMBERS ie 
p 


The result of the minimum | function is the smaller of the two arguments. 


EXAMPLES: 
AGS 
hes 
ALE 

5 


CERXEIL AXA 


Ae my 
Cel Ww FY 
fies 2 BF 
men 

he ee pe ge 


Problems: Using the Maximum and Minimum Functions 


1. Find the largest dollar expenditure for the following gasoline 


purchases: 

a. 16.8 gal at 57.9 cents per gal 
b. 13.5 gal at 60.9 cents per gal 
c. 15.6 gal at 62.9 cents per gal 


2. For the following purchases, find the smallest quantity of nuts 
received: 
a. 71 cents for walnuts at 33 cents per Ib 


b. 53 cents for cashews at 27 cents per |b 
c. 64 cents for pecans at 29 cents per Ib. 


Suggested Solutions 


Problem 7: 


CLO. 82 579 POLS Se 6090 TLE. Gx. 429 


7.8124 


Problem 2: 


1. PG3 
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FINDING THE INDEX OF A VALUE IN A VECTOR 
pf 


When you want to find out if a value is an element in a vector, and if it 
is, which element it is, you use the index of function ( 1 ). The index of 
function gives you the position (index) of the first occurrence in the 

left argument of the values in the right argument. If a value in the right 
argument is not in the left argument, the result is 1 plus the length of the 
left argument. 


EXAMPLES: 


Ne 
ed BA 23 B16 29iN 


Ae ARCTEFG 


Ar’ CAFE’ \ 

ae Seto ae 
eo 
Cel & 2S Wb & Index of the first occurrence. 
(1k 

AS oS — Index generator function. 
Cid? 

G Lo index of function. 


Ot, 


Value does not occur in the 
left argument; the result is 1 
plus the length of the left 
argument. 


GENERATING A RANDOM SEQUENCE OF NUMBERS 
Q 


In Chapter 3, you used the roll function (? with one argument) to generate 
one random number. But by using the deal function (? with two arguments) 
you Can generate a random sequence of numbers without generating the 
same number twice. That is, the deal function generates the number of 
random numbers specified by the left argument from 1 through the value 
specified by the right argument. The random numbers are selected so that 
no two numbers are the same. Therefore, the left argument cannot be 
greater than the right argument. If you specify the left argument equal 

to the right argument, you get all the numbers from 1 through the number 
specified by the right argument, in random order. 


EXAMPLES: 


oe ae 9 
eu of 


4 


May be any two different numbers 
L07°10 between 1 and 5. 


~ 3 8 10697 24 i 7 Se 
These numbers can be in any order, as 


you will see if you enter this 
instruction several times. 


SELECTING CERTAIN ELEMENTS (COMPRESSING) 


FROM A VECTOR OR MATRIX 
/ 


You can use the compress function / to select certain elements from a 
vector or matrix. The left argument must be a vector of all 1’s and 0's 
or an expression that results in such a vector. When you select elements 
from a vector the number of elements in each argument must be the 
same; the corresponding elements of the right argument are retained for 
each 7 in the left argument. 


EXAMPLES: 


Vel 234 5 6 7 8 
Loo td 0 2 1 d7¥ 


000 06 0 0 0 O07¥ 
TT ——nn——— Result is an empty vector. 

Ace) O00 0 00 0 2 

ASY 


1 0 t G7’ ABCT 
ACS 
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When selecting elements from a matrix, you must select and omit entire 
rows or columns. To do this, you must specify the coordinate (rows or 
columns) to be acted on by using an index value [I]. The index value is 
1 if the first coordinate (rows) will be acted on and 2 if the second 
coordinate (columns) will be acted on. 


EXAMPLES: 


Bes Werle 
i 


1 > 4 


ee | es Remember, the left argument must contain a 
ee oa 1 for each item to be selected and a 0 for each 
item to be omitted. 
Oot O/F 168 
See ae {___ the first coordinate (rows) is specified. 
1 0 4 O/T SIG 
1 4 t_____ The second coordinate (columns) is specified. 
a : 
9 11 
1 Oo 1 0/8 
i % 
op Ee If no index entry is specified, the last 
evan coordinate (columns) is acted on. 


EXPANDING A VECTOR OR MATRIX 
/ 


You can use the expand \ function to insert blanks or zeros in a 

vector or matrix. The left argument must be a vector of all 1’s or O’s or 
an expression that results in such a vector. The number of 1’s in the 
left argument must be equal to the number of elernents in the right 
argument. The 0's in the left argument indicate where the blanks or 
zeros will be inserted; blanks are inserted in a character vector or matrix 
and zeros are inserted in a numeric vector or matrix. 


EXAMPLES: 


Lod 6 2 GO TNC ABC 


When you expand a matrix, entire rows or columns of blanks or zeros 
are inserted. As when using the compress function, you can specify the 
coordinate (rows or columns) to be acted on by using an index value 
[1]. The index value is 1 if the first coordinate (rows) is to be acted on 
and 2 if the second coordinate (columns) is to be acted on. If no index 
entry is specified, the last coordinate (columns) is acted on. 


EXAMPLES: 


He “> Xk ; 
Pies aoe The left argument must contain a 1 for each 


row or column being acted on. That is, the 


a wy 

i a number of ones in the left argument must be 
OY. Lo iNroqg equal to the coordinate being acted on (for 
Lo 2 sas example, the number of rows or columns). 

3 0 4 Insert columns. 


oY Insert rows. 


‘ARC If no index entry is specified, the last 


coordinate (columns) is acted on. 


Problems: Using the Compress and Expand Functions 


1. Define a vector called ACCTS containing these five accounts: 56 
103. 100 = 13 0. Select those with balances of $100 or 
more. 


2. Define the matrix DATA<3 3p 19. Then insert a row in 
DATA, with the values 20, 21, and 22, after the first row. 


Possible Solutions 


Problem 7: 


ACUITSe44 LA .tt 1s bt 
CACCTS Ss 1002 2ACCTS 
LO4 106 
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Problem 2: 


NATAGS Spry 
ATA 


Lo 

y 4 

% @ 
NATAée1 O 2 IStLaDATA 
QATA 

Los. Ss 


G60 6 
YE 


NATAL; Te 20 24 22 
LATA 

Le oS 

20 21 22 

eo oS 

eS 


JOINING TWO ITEMS TOGETHER (5) 


You use the catenate function (,) to join two vectors together to make 

a single vector by placing a comma between the left and right arguments. 
The number of elements in the resulting vector is the sum of the number 
of elements in the two vectors being joined (catenated). 


EXAMPLES: 


med 2 
Bele SG 
i, i 


123 4 oO & 


(Dk 
CATENAT ION 


ae 

TOMGIN ERROR A vector must be either all numbers or all 
AL characters; therefore, you cannot catenate 
A character data to numeric data. 


You also use the catenate function to join two matrices together. To do 
this, you can use an index value [1] to specify which coordinate is to be 
extended (that is, whether the number of rows or the number of columns 

is to increase). The index value is 1 if the first coordinate (number of 

rows) is to be extended and 2 if the second coordinate (number of columns) 
is to be extended. When no coordinate is specified, the last coordinate 
(columns) is acted on. 


EXAMPLES: 


At? 2a 
Bee Vole yt 


ray 
1 2 
3 OY 
is 
& 6 
? 8 
As Cg You have just joined two columns to two 
1 2 5 4& existing columns (increased the number of 
Sy FB columns). 
Ak 
12.5 4 Ss, 
3 4 FY 8 When no coordinate is specified, the last 
A, ELI coordinate (columns) is acted on. 
1 2 
3 
ou 6 In this case, you have joined two rows to two 
Y 8 existing rows (increased the number of rows). 


When you catenate two matrices, the arguments must conform—that is 
the lengths of the columns (number of rows) must be the same if the 
columns are to be catenated and the length of the rows (number of 
columns) must be the same if the rows are being catenated. 


’ 
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EXAMPLES: 


A&? Bett 


rf 
ye 
a 
(Te? Sad 
C 
& & & 
a & & 
&.0i14IC 
LENGTH ERROR -————The length error was caused because the row 
Aaa C coordinate was specified when A and C have rows 
A of different lengths. 
Siw 
“Ue 
A, 210 ~~ Note that the matrices can be joined along the 
YY & & & column coordinate, since the lengths of the 
ye & & & columns are the same. 


Building a Vector of Results Using Catenation 


Suppose that as you work through a series of problems you want to 
accumulate the answers. One way to do this is to catenate each new 
result to a vector of results previously obtained. If the most recent 
result is in a variable called LATEST and all the former results are in a 
vector called RESULT, you could use the following instruction: 


RESULT« RESULT,LATEST 


Note: The first time this instruction is executed, there is no value for 
RESULT. Therefore, before you use this instruction, you should enter 
the following instruction: 


RESULT<10 


This instruction gives RESULT an initial value (makes it an empty 
vector). 


EXAMPLES: 


LATEST 1LO+8 


RESULTE RESULT, LATEST 
VALUE ERROR~~———\-_—————_ RESULT does not have a 
RESULT¢ RESULT, LATEST value; therefore, it is not a 
is variable and cannot be used 
in an instruction. 


(RRR Give RESULT an initial 
RESULT 40 


value (empty vector). 
RESULT 


T= Blank display. 

RESUL Te RESULT, LATEST 

RESULT -—_—_ ————————- Now RESULT can be used. 
1S 

LATEST¢ 15410 

RESULT¢ RESULT, LATEST 

RESULT 


Problem: Using the Catenate Function 
Assign codes to variables as follows: A<‘l’, B< ‘T’, C<‘D’, D<‘R’, E<’GH’, 
F< ‘YO’, G<‘ ', and H<-‘U’. Then see what message is displayed if you 


catenate the variables in the following sequence: 


FHGCACGABGDAEB 


APL Functions That Require Two Arguments 


53 


54 


Possible Solution 


Ae Ty! 

Ret 

Cet 

Ne Re! 

Ee GH 

Re YC! 

Gt . . 

He U! 
F>HLG,C,A,C,6,.0,8,6,0,4A.E, ik 

YOU DIN TT RIGHT 


FINDING THE LOGARITHM OF A NUMBER 
Oo P 


You use the logarithm @ function to find the log of the right argument to 
the base specified by the left argument. The log of a number B to a base 
A is the power needed to raise A to the value B. 


EXAMPLES: 
Ae? 
Re AMS 
i 

a 


AGT: —————— The log of B to the base A. 


Problem: Using the Logarithm Function 
1. What is the logarithm of 256 to the base 2? 


2. To what power must 10 be raised in order for it to equal 100000? 


Possible Solutions 


Problem 7: 


Oe 


8 


Problem 2: 
LOe@100000 
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Collectively (Reduction) 


It is often useful to have the sum (or the product, or the maximum, for 
example) of all the elements in a vector. APL has a simple procedure for 
applying the same function to all the elements of a vector collectively. 
This function is called reduction, because it reduces a numeric vector 
down to a single number that represents the sum, the product, or the 
maximum, for example. The reduction operator is /. The left argument 
is the function that is applied to all the elements in a vector; the vector 
is the right argument. 


You may have noticed that the reduction operator and the compress 
function have the same symbol. However, you can tell the difference 
between the compress function and the reduction operator by the left 
argument. For the compress function, the left argument is a vector of 
1's and 0’s and for the reduction operator, the left argument is an APL 
built-in function. 


PLUS REDUCTION 


EXAMPLES: 

aed 2 3 uw 3 

+ vA ry 
1 

Let ot lee Adding all the elements of A together is the 
1S same as +/A. 


Using Plus Reduction To Find the Average 


The reduction operator is useful for finding the average of the elements 
in a vector. Suppose vector X is as follows: 


The following expression could be used to find the average of the 
elements in X: 


AVGE C+/X d= 0X 
AVG 


we fal 


Now let’s analyze the previous expression. 


1. 


We find the number of elements in X (the length of X): 


Then we calculate the sum of the elements in X: 


Now we can find the average by dividing 16.5 by 6: 


AVG 14S . +5 


AVES 
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Problems: Using Plus Reduction 


1. Using reduction, find the average amount that a certain family 
spends each week on food. The weekly grocery bills for November 
were $31.05, $29.78, $25.44, and $35.98. 


2. Temperatures of a laboratory solution were recorded over a 
12-hour period: 


75.8° 
71.9° 
77.0° 
80.3° 
85.1° 
82.2° 
83.2° 
84.9° 
85.3° 
85.0° 
82.5° 
80.9° 
78.4° 


AM — 
AM _ 


Find the average temperature. 


Possible Solutions 


Problem 7: 


BILLSe31.05 29.78 25.44 35.98 
AVG (+/BILLS)+eBILLS 


AVES 


30.5634 


BO. P42 


Problem 2: 


TEMPe 75.8 71.9 77.0 80.3 G3.1 62.2 83.2 84.9 85.3 85.0 G2, 
3 80.9 78.4 


AVGe (+/TEMP D+ eTEMP 


AVG 


Using Plus Reduction to Sum the Products of Two Vectors 


Suppose that PRICE is a variable that contains the price list for various 
items sold by a store, and Q1 and Q2 are two vectors indicating the 
quantity of these items ordered by two customers. Then the total bill 
for customer 1 is the sum of the product of PRICE times Q1, and the 
total bill for customer 2 is the sum of the product of PRICE times Q2. 


EXAMPLES: 


PRICE®.66 1.40 27,10 2.39 14,00 7.460 8.45 2.980 
QletU 0 2 t 00 0 0 

Qzel2 7 05 0 0 0 10 

+/Q1XPRICE 


+/Q2xPRICE 


MINUS REDUCTION (ALTERNATING SUM) 


EXAMPLES: 
Aes 2 Ly 
“fA 
vee me |e -/A is the same as this expression. 


may 


The following illustration shows why the answer is _ 2. 


Direction of processing is from right to left. 


3-2-1 - 4 +————First operation (subtract 4 from 1; the result is ~3). 


—_—_——_— 
2 - ~3 
Second operation (subtract 3 from 2; the result 
is 5). 
2 + 3 
VS 
3 - 5 ~«~——______ Third operation (subtract 5 from 3; the final result 
Ne _-— 
is 2). 
Result. 
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MAXIMUM REDUCTION: FINDING THE LARGEST VALUE IN A VECTOR 


To select the largest single element in a vector, you can reduce the 
vector using the maximum | function. 


EXAMPLES: 


BALNUE¢ 62.15 127 4.42 18.65 
P/BALCUE 


Amount owed 
by all the 


Le? customers of a 
store. 
ae 
Largest amount 


owed. 


MINIMUM REDUCTION: FINDING THE SMALLEST VALUE IN A VECTOR 


To select the smallest single element in a vector, you can reduce the 
vector using the minimum | function. 


EXAMPLES: 


NUMBERe 1 16 4 % oP? 
L /NUMBER 


OR REDUCTION: CHECKING FOR A SPECIFIC VALUE IN A VECTOR 


Suppose you want to know whether a certain value exists in a long 
vector. You could use Or reduction (v) to find the answer. 


EXAMPLES: 
‘aa Generate a vector of 50 random numbers. 
NUMBER ate 00 The result of NUMBERS=8 is a vector 
V/NUMBERS consisting of a O for each element of 


NUMBERS that does not equal 8 and a 

1 for any element that does equal 8. 
When the vector (result of NUMBERS=8) 
is reduced (the Or function is placed 
between each element), the result is 1 if 
at least one of the elements was 1. 

A displayed result of 1 indicates that the 


value 8 was in NUMBERS and a O 
indicates that it was not. 


AND REDUCTION: CHECKING FOR ALL VALUES IN TWO VECTORS 
BEING EQUAL 


You can use And reduction (,)to determine whether corresponding 
elements of two vectors are equal. 


EXAMPLES: 
Two vectors 
that have the 
KEVY¢L. Ol 1.7463 1.888 41,2346 1,22 72 same number 
LOCKe 1. O1 1,763 1,998 1.2346 1.0272 of elements. 


ASKEY= LOCK 
0 


At least one of 
the elements of 
KEY does not 
match the 
corresponding 
element of 
LOCK. 
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This chapter contains a summary of the things you can do with the APL 
built-in functions. Some of the functions have already been discussed 

in the previous chapters and all of the functions are described in the /BM 
5110 APL Reference Manual, SA21-9303. Also, there is an example 
included for each function; you should enter these examples on your 
5110 to see how these functions work. 


Note: Many of these functions provide special computational capabilities. 


NOW LET'S LOOK AT THE THINGS YOU CAN DO 


Things You Can Do Function Name Keys 


APL Functions That Require One Argument (see Chapter 3 
for more information) 


e Determine the next larger whole Ceiling 
number : 


ru, 48 & «——————If the number is already a whole number, 


er) the same number is the result. 
e Determine the next smaller whole Floor 
number D 


14,48 2 ————If the number is already a whole number, 
yo 2 the same number is the result. 


e Sort a string of numbers in Grade up a 
ascending order ba 


hae ds 7 Indices of A in ascending order 
GO oo ob ae 
At da 1———\— Sorts A using the indices 


Ae ee os Ee 


Things You Can Do Function Name Keys 


@ Sort a string of numbers in Grade down ea 
descending order G 


PAGS PF 2 Ff Indices of A in descending order 
4243 5—— 
ALL! P&I] Sorts A using the indices 


9 7 3 2 1 
@ Generate a random number Roll 
Q 
?G 
3 Thee result can be any number between 
1 and 6. 
e Generate a consecutive string of Index generator 
numbers 
VS 
Leg 4 §—————————_ Generates a string of five consecutive 
numbers. 
e Determine the length of a string Shape 
or the number of rows and : 


columns in a table 


par same instruction (the number of rows and 
MATRIX columns) 
Loe oS 
ys Reshape function (discussed in Chapter 2) 


Shape function 
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Things You Can Do 


Function Name 


Keys 


APL Functions That Require Two Arguments (see Chapter 4 


for more information) 


The result from the following six functions is 1 if the relationship 
specified by the APL function is true; otherwise the result is 0. 


Determine whether two values 
are equal 


Determine whether the left 
argument is greater than the 
right argument 


Loe? 


Determine whether the left 
argument is less than the right 
argument 


Determine whether the left 
argument is greater than or equal 
to the right argument 


Pee. “ie 


Determine whether the left 
argument is less than or equal to 
the right argument 


Determine whether two values 
are not equal 


re a) 
(era i 


Equal to 


Greater than 


Less than 


Greater than or 
equal to 


Less than or 
equal to 


Not equal to 


(:) 


> 5 
7 


< 
3 


> 
6 


Things You Can Do Function Name Keys 


The following two logical functions are usually used to check 
the results from relational operations. Logical functions can 
use only 1’s and 0's as arguments. The result is 1 when the 

condition being checked for is met; otherwise, the result is 0. 


@ Determine whether two conditions And 
are true 0 
fad a 
1 oO 
e Determine whether at least one Or 
of two conditions is true 9 
lvl oO 
| 
@ Find the larger of two numbers Maximum 
S 
ae A 
a 
e@ Find the smaller of two numbers Minimum 


e-] 


my | j 
tad lake 


e Find the index of a given value Index of 
in a vector 


SP oe Oe ae 
8 Thee right argument is found in the third 
position of the left argument, which is a 


vector. 


@ Generate a specific number of Deal 
different random numbers Ss 


SPS 


A Y-+-_  — Can be any three different numbers 
between 1 and 6 
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Things You Can Do Function Name Keys 


e Compress (select certain elements Compress 
from) a vector or matrix f 


10 0 1/42 3 4 S 
eae Ak Selects the elements that correspond to 
the ones in the left argument 


e €xpand a vector or matrix Expand 
/ 
1040 2 0 21 ONE 3 YU OS 


ee SSS Inserts elements according to the zeros 
in the left argument 


e Join two arguments together Catenate ( : ] 


‘CAT CENT CATION: 
CATENAT TON 


e Find the log of a number Logarithm 
fe) p 


LOG Log of 8 to the base 2 


APL Functions In Addition To The Ones Already Discussed In 
Previous Chapters (see the [BM 5110 APL Reference Manual, 
SA21-9303, for more information) 


e Change the sign of a number Negation 
4 


e Find the sign of a number Signum 
x 


pao ee | ee 
“40 1 Thee result is ‘1 for a negative number, 
O for 0, and 1 for a positive number. 


© Find the reciprocal of a number Reciprocal 
x 


Things You Can Do 
@ Raise e (2.71828) to a power 


“¥1 3 
2, 7183 20.086 


e@ Find the log of a number to the 
base e 


@2,. 7183 20,086 


e@ Multiply a number by pi 
(3.14159) 


aL 3 


S. LIS 9 BUS 


e@ Find the product of all whole 
numbers between 1 and a 
specified number 


1 Ay. 


Function Name 


Exponential 


Natural log 


Pi times 


Factorial 


Keys 


* 
P 


t * 
O P 


LJ 


2k. <——__________———_——— The result is the same as 1x2x3x4. 


e Changeal1toaQoraOtoa1 Logical not 
: 
“i 0 
of 
e Determine whether at least one Nand 
of two conditions is false 0 J 
LA4 9 +—————— The result is 1 when at least one argument 


e Determine whether two conditions 


are false 


Nor 


is O; otherwise the result is O. 


Vv ‘ 
g T 


The result is 1 when both arguments are 0; 
otherwise the result is 0. 
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Things You Can Do 


e@ Change a scalar or matrix into a 
vector 


MATRIX¢2 Seid 
MATRIX 

1 ae 

Yoo 4 
»MATRIX 


Function Name Keys 


Ravel 


139 3 y % 46 —————— The result is a vector. 


. 


e Execute a character string as an 
APL expression 


} ‘oy ' 


e Convert numeric data into 
character data 


Execute 
J 


Format : T 
od N 


Ae yy. + How to use this function with two arguments 
ra is discussed in the /BM 5110 APL Reference 


Oy ~ 
eT 


Manual, SA21-9303. 


ey This is a character value. 


“ i ae 
A is a two-element (character) vector. 


e Find the value of a number 
without regard to the sign of 
the number 


[3 "Ua 
mA WG 


e Invert a square matrix or compute 
the pseudo-inverse of a rectangu- 
lar matrix 


Hat? Pol 3 5 7? 
“1.875 ee 


0.462% u,125 
e Reverse the elements in a vector 
or matrix 


OLIVE 
EVIL 


Absolute value 
M 


Matrix inverse 


7 a 
x a 


Reverse | O 
M oO 


Things You Can Do Function Name Keys 


e@ Find the remainder left over from Residue (remainder) Ey 
a divide operation 


318 


2 2 is the remainder of 8 divided by 3. 


@ Find the values for the trigono- Circular 7 
metric functions of an angle 


Maha ea left argument specifies the trigonometric 
i eee function (in this case, tangent). 
The result is the tangent of 45° (7 = 4 radians). 


e@ Find the number of combinations Binomial 
of a number taking so many at a (combination) K 
time 

ty 


& << ——_—__$__—_—_—____________ Four items taken two at a time can make 
six different combinations. 


e Find out if a certain value (left Membership @ 
argument) exists in a vector or 
matrix 


"ARC" & " BANANA ~— The result is 1 if the value in the left argument 


Loi 0 exists in the right argument; otherwise the 
result is 0. 
e@ Express a value in another Decode (base value) ea 
number system 


24h 60 SOa1. 30 VS 
O41 Ss <——_—_——__—_—_——_——————— Expresses 1 hour 30 minutes 15 seconds 
in all seconds 


e Represent a value in a specified Encode 
number system (representation) N 
24H 60 607TSuU1S 


1 40 15 +————————_ Represents 5415 seconds in hours, minutes, 
and seconds 
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Function Name 


Things You Can Do 
Matrix divide 


e Solve one or more sets of linear 
equations with coefficient 


matrices 


26 FHRe? 2e3 5S 1 2 


~J 
a 


Take 
Ly 


e Take acertain number of elements 
from a vector or matrix 


3f4ae1 2 3 4 S 


vector. 


e Drop acertain number of elements Drop 
U 


from a vector or matrix 


The result is the elements remaining after 
the specified number of elements have 


been dropped. 


iy 


e Join two arguments together by Laminate 
forming an array with an 
additional dimension 
Join along a new first dimension. 


Seed 4 OOF OG 


S.4 Sy 


| ae ee Camere 
> Tw vectors are joined to form a matrix. 


Rotate 
VM 


e Rotate the elements in a vector 
or matrix as specified by the 


left argument 


Sh) 2 3 uO 
a > Rotates the vector two positions 


a ee a | 


Things You Can Do Function Name Keys 


e Create data arrangements with at Reshape Z 
least one dimension (a data 
arrangement with two dimensions 
has both rows and columns) 

_ +————_ Each number in the left argument is called 

ARRAYe 2 3 Sei.iB a coordinate—this N-rank array has three 


ARRA coordinates. 
: ee 
yo FG Last coordinate is the columns. 
_ 7 ye 
é 7 2 Next to the last coordinate specifies rows. 
i190 ti i? . Leftmost coordinate is the planes. 
13 16 1S Planes 
16 1? 16 i ee 
ARRAY 2:35 47 You can index elements within N-rank arrays 
14 by putting a semicolon between coordinates. 
@ Interchange coordinates (such as Transpose or 
rows and columns of a matrix) generalized 0 : 
of an array transpose 
QE RAY +s —__ When used with one argument, this function 
1 $10 reverses the coordinates. 
a 
ee Note: This function could also be used with 
a left argument that specifies how the 
~ ii coordinates are to be interchanged. 
OLY 
go 1? 
Oo ches 
£5 
9 19 
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Things You Can Do Operator Name Keys 
APL Operators 
An APL operator applies certain built-in functions to all the 


elements of a vector or matrix. The reduction operator has 
already been discussed in Chapter 5. 


e Apply the same function Reduction 
collectively to all the elements : 


of a vector 


[fae & 0 TS -2 


rt The largest element 


The smallest element 


e Apply the same function Scan ae 
cumulatively to each element ; 
~ of a vector (the result of each 


operation is used in the next 
operation) 


"> 
Ae 


#\1 2 3 4 


13 6 16 
1. 
1 
142 The scan function works the same as if you 
4 entered these instructions. Remember, the 
Lee individual functions are executed from right 
& to left. 
Lene el 


e Generate operation tables for Outer product 
various APL functions and data Rae 


hme, XA 
| 2 A OY. 
an | & ‘3 A multiplication table of numbers 
es <a 1 through 4 
“Ye te 16 


Things You Can Do Operator Name Keys 


@ Find the matrix product of two Inner product 
matrices 


AC2 2el 2 3 y 

Be? fe S 46 7 & 

At. XB 
a << The matrix product of matrices A and B 
WS SO 


e Table look-up Inner product 


Ae lee JOH UANE JACK KATE ' 
A 
DEN 
JANE 
AAI 
KATE 
"JOHN aA tg 
1 oo 0 -~—_——___- John is the first name in the table. 
"JACK A, =A 
nok ee ——________ Jack is the third name in the table. 
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WHAT IS FUNCTION DEFINITION? 


Although APL has many built-in functions, there will be times when 
you want a special function to solve a problem. APL allows you to 

define your own functions (called user-defined functions) and store 

them for repeated use. 


HOW IS A FUNCTION DEFINED? 
G 


You use existing APL functions to create a new user-defined function. 
The new function consists of: 


e A function header containing the name of the function and other 
information (the types of function headers are discussed later in 
this chapter). 


e An expression or series of expressions, called statements, which define 
the operation(s) to be performed. 


When executing APL expressions, the IBM 5110 is in execution mode; 
however, before a new function can be defined, the mode must be 
changed to function definition mode. The V (del) symbol is used to 
change the 5110 from one mode to another. for example, to change 
from execution mode to function definition mode, a V is entered as the 
first character in the function header; then after the function is defined, 
another V is entered to close the function definition and change the 
mode back to execution mode. Once the 5110 is back in execution 
mode, you can execute your user-defined function. 


Now, to show how a function is defined, let’s create a function to find 
the hypotenuse of a right triangle. The expression used for this could 
be written as ((A*2)+(B*2))*.5, where we square the lengths of the two 
sides A and B and then take the square root of their sum, which is the 
length of the hypotenuse. The function must have a name by which it 
can be identified, so let’s name this function HYP. Now enter the 
opening v (to place the 5110 in function definition mode) and the 
function header, as follows: 


YHPeaA HYP i +—— Function header. 
Code 
APL responds with the number of the first 


statement (expression) to be entered. 


As each statement is entered, the next statement number is displayed. 
Now enter the remainder of the function as follows: 


HPe (CA 2) 4+ C2) Doe, +———— Expression 


V Perea cre eee eee = 
Closing V — Changes mode back 


to execution mode. 


Notice that the names in the function header (other than the function 
name itself) are all used in the body of the function. In particular, 
notice how the result variable name, HP, is assigned the final result by a 
statement in the function. 


The display screen will now look like this: 


VHPGA HYP kt 
CLD MPG (CAD) 4+ (BE) DH, 5 
C21 0 


Note: \f you make a mistake when entering this function, see What To Do 
/f You Make a Mistake When Defining Your Function \ater in this chapter. 


When you entered the closing v, the function HYP was stored in your 
active workspace, so you can use it just like any other APL function 
with two arguments. 


EXAMPLE: 
Lengths of the two sides. 
3 HYP 4 
= Length of the hypotenuse. 
Xe& 
Ye 
KX HYP ¥ 
LQ 
Res Like other APL functions, the arguments can be 
Let in different forms. 
R HYP OL 
~ 10 


Whenever you want to use HYP, just enter its name with the arguments 
you want. The symbol for the calculation of the hypotenuse of a 
right triangle is HYP, just as the symbol for addition is +. 
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A function can have only one instruction, like HYP, or it can contain 
many instructions. 


EXAMPLE: 


VHPeAa HYPL, i ~—— The function HYP could also have been 


Cla ARe Ax? defined like this. 
20) Bee Ree 
C3] SeAP+k2 a Note that the closing VY can also be on the 
CARD HP e Soe, SV same line as the last instruction. 
6 HYPL 
Q——__—_____________. Same result as HYP. 


Problems: Using Function Definition 


1. Define a function that displays the sum of any two numbers. 
Then use the function. 


2. Define a function that displays the area of any rectangle. 
Then use the function. 


Possible Solutions 


Problem 7: 


VSemM SUM N 
Did S¢M+ny 
& SUM 3 


9 
Problem 2: 
VAe¢LENGTH AREA WITTH 
Cl A&LENGTHZWIOTH 
On ae 


WY AREA & 
20 


TESTING YOUR FUNCTION BEFORE USING IT 
Once you define your function, you should always try using it with 
data that will give you a known result. For example, suppose that in 


the function HYP you used the following expression by mistake: 


a Should have been x 
CCAM IE CREP DX 


You would get an answer, but it would not be the right answer for the 
hypotenuse of a right triangle. 


When you test your function, one of the following will occur: 

e The 5110 will display the result you expect. 

e@ The 5110 will display an error message. 

e The 5110 will display a result, but not the result you expect. 


e Nothing will happen. 


If the 5110 Displays the Result You Expect 
Great! Your function works. 


Note: Even though your function worked one time, you may want to 
test it some more to make sure it will work for each application you 
intend to use it for. 


If the 5110 Displays an Error Message 


You can use the /BM 5110 APL Reference Manual, SA21-9303, to find 
out what the error message means and what you must do to correct it. 


Note. An error condition will cause the execution of your function to 
stop; see Chapter 8 for more information on what to do when your 
function stops executing. 


If the 5110 Displays a Result Other Than the One You Expect, or 
If Nothing Happens 


In either of these cases, you have two alternatives: 


e Display the entire function and check it for errors. Displaying the 
Entire Function is discussed later in this chapter. 


e Use the trace and stop features (discussed next) to help find the 
problem. 


Note: When a user-defined function is used and nothing happens 
(that is, neither result nor the cursor appears on the display screen) 
or a result is repeated continuously, the function is probably 

looping. \n this case, press the ATTN key to stop (suspend) function 
execution. Chapter 8 contains information on what to do when your 
function stops. 
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HOW TO USE THE TRACE AND STOP FEATURES 
ic H S oH 


Trace TA 


The trace feature allows you to watch the execution of your function, 
statement by statement. That is, the final result calculated for each 
statement traced is displayed. You can either trace all of the statements 
or just certain statements in a function. To use the trace feature, 

enter TA, the function name, « , and the statement numbers to be 
traced. For example: 


TAEXOAMPLE¢1 2 3 Wo & 6 
ee ee ee Oe 
eas statement numbers to be traced 


The name of the function to be traced 


The previous statement could also be entered as follows: 


TAEXAMPLE 16 


Generates a vector of numbers from 1 to 6 


Stop SA 


The stop feature allows you to stop the execution of your function just 
before a specified statement is executed. That is, function execution 

is temporarily suspended (suspended functions will be discussed in greater 
detail in Chapter 8). After function execution has stopped, the 5110 
displays the number of the next statement to be executed. To use the 
stop feature, enter Sj, the function name, <, and the numbers of the 
statements before which function execution is to stop. For example: 


SAE XAMPLEG A & 
ae 


The specified statement numbers 


The name of the function 


After function execution has stopped, you can start it again by entering 
+f] LC. [LC (line counter) is a system variable that contains the next 
statement number to be executed; see Chapter 9 for more information 
about system variables, and the /BM 57170 APL Reference Manual, 
SA21-9303, for a complete description of the [] LC system variable. 


Now let's use trace and stop to find a problem in a function. 


EXAMPLES: 


VHP¢A HYPX & 
Ci ‘THE HYPOTENUSE 1 ' ~——Defines a function that calculates the 
R27 APEAKD hypotenuse of a right triangle. 
CS] B2ekx2 
Cu] S¢A2+h2 


CSI HPeSx , ay 
Tests the function using data for which 


4S HYPX & pee correct result is known. The result 


This function has an error in it. 


THE HYPOTENUSE 1S should be 5. 
13,5 


Using the trace feature to find the problem 
TAHYPX¢2 3 yo & 
SO HYPX ¥. 
THE HYPOTENUSE 
HYPXE27 
HYPXEST 14 


HYPX CT 2 The correct result was obtained in each 
HYPXES ] 12,5 statement except statement 5; therefore, 
y He gear statement 5 probably contains the error. 


TAHYP Xe. Q To turn off the trace feature, use 10 as 
the statement to be traced. 


The 5110 responds with the function 
name, statement number, and the result 
of the statement being traced. 


SAHY PRE FF 
Using the stop feature to find the problem 
A HYPX 4p 


THE HYPOTENUSE IS 
The 5110 responds with the function 


HY PX Cu —_—____ name and the next statement number 


Ag to be executed. 
Y ass 

Re When the function is stopped, you can 
Lé enter the variables to see if they con- 


tain the expected values. 


+(]L.C ~———————_—_———_—_ Continue execution by entering >[]LC. 


HYPXCS 3 —_—___ Execution stops at the next statement 


ay specified for the stop feature. 
ea 
SLC All the variables contained the correct 
ha aad values; therefore, statement 5 must be 
in error. 


SAHY PX. 0 
Oe a To turn off the stop feature, use 10 as 


the statement to be stopped at. 


Note: How to correct an error ina 
function is discussed next. 
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WHAT TO DO IF YOU MAKE A MISTAKE WHEN DEFINING 
YOUR FUNCTION 


If you make a mistake when defining your function, you can correct it 
by editing the function. When editing a function, you can do the 
following: 

e Display the entire function. 

e Add one or more statements at the end of the function. 

e Replace statements. 

e Insert one or more statements. 


@ Delete a statement from the function. 


e Display a specific statement or from a specific statement to the end 
of the function. 


e Modify a single statement. 


If you notice your mistake as you are defining your function, you can 
correct it without reopening the function definition (the 5110 is already 
in function definition mode). However, if the function definition is 
closed, you must first reopen it. To do this, you must enter the v 
followed only by the function name. If you enter the complete function 
header, you will get an error message. 


Now, let's define a function to use in doing some function editing. 
Enter the following: 


VSTAT Xx 
Lid Nepx 

(20 (4+/X EN 
USI 17% 

ae ee: 


This function calculates the average, smallest, and largest number in a 
vector of numbers. Notice that this function does not have a result 
variable in the function header; however, it will still display the results. 
The reason for having a result variable in your function will be 
discussed later. 


Displaying the Entire Function 
| L 


To display a function, you enter [[]] immediately after any statement 
number or as shown in the following example. 


EXAMPLE: 


This instruction opens, displays, and closes 


VSTATEOIY the function definition. 
¥VoSTAT xX 

Ne ox 

C+/% +N \_-———-— Displayed function. 

L. “XxX 


| 
| 7 
i] 
ni wad Try the function. 


STAT 2 9 1 
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Adding One or More Statements at the End of the Function 


To add statements to a function, you open the function definition and 
the number of the first available line is displayed. Then you can enter 
the statements you want to add. 


EXAMPLE: 


The 5110 displays the number of the first 
available line. 


STAT —\—\———- Open the function. 
CS7 CP /K oe EL SKY 

ere Add this statement to find the range of the 
numbers in the vector. The V closes the function 
(you are only adcling one line). 


¥STAT CLAV—— Display the function. 


VY STAT xX 
moa Ne a3 
La So Aca ~———- Displayed function 
I. 4] 17% : 
"by [ 7X 
Sea | (PSX | 7K 


STAY 9 2 1.~——Try the function. 


Replacing Statements within a Function 


To replace statements, the statement number to be replaced must be 
enclosed in brackets [ ] followed by the new statement. 


EXAMPLE: 


¥YSTAT C3 This instruction opens and displays the 


¥ STAT xX function. 
ma Nt aX 
fi] C+/X) +N 
4a |. 7X Displayed function. 
a wes 
iS 2 (PSX) | 7X 
yV 


The 5110 displays the number of the first 
available fine. 


f , — Notice that you can specify another state- 
Réd Red C+ exe oxy ment number by enclosing it in brackets. 
Now, replace statement 2 with this state- 
ment for finding the average. The V closes 
the function. 
In this example, you could also use the scroll 
down key and scroll up key @ 


to place statement 2 on the input line 1. Then 
statement 2 can be corrected; however, you 
must make sure that statement 3 does not 
appear on line 0 before you press EXECUTE. 


YSTATCE IV —————- Display the modified function. 
YO STAT X 
oe Ne oX 


eae | Cb X) + ok 
3c am ~————— Displayed function. 
[7 2 [7x 
ane Cf /XI ££ 7X 

¥ 

STAT Y | 2 

iy. 
I 
Y 
3 
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Inserting One or More Statements in a Function 


To insert statements in a function, you must use a decimal statement 
number that is between the numbers of the statements where you want 
to insert the new statement. For example, to insert a statement between 
statements 1 and 2, you could use the statement number 1.5 or any 
decimal number between 1 and 2. 


EXAMPLE: 


Open the function. 


The 5110 displays the number of the first 
blank line. 


ré) CL.“ x <——————— Insert a staternent between statements 1 and 2; 
; CAE: the inserted statement displays the vector of 
Fi.4] ¥ numbers. 


If you do not enter V , the 5110 responds 
with another decimal statement number. 


Enter the closing V. 


YSTATCULIY ————— Display the function. 
¥VoSTAT xX 


ae ae Me ox 
tee x 
eo (4+/X)+ox% U)  — Notice that the 5110 has renumbered the 
rp {| “x statement numbers. 
Lea rex 
Cé 1] CP /Kon1 7X 

y 

STAT Y 2 4. 

? | 
hy 
1 
G 
as 


Deleting a Statement from a Function 
_#H 


To delete a statement from a function, you enter [An] , where n is the 
number of the statement you want to delete. 


EXAMPLE: 


YSTATEI Open and display the function. 


VY STAT xX 
La Ne ox 
ret x 
3c C+/X) + pX __——_ Displayed function. 
[2] 1. “x 
re PAX 


f 


6 CP SX) «| 7X The 5110 displays the next available statement 


CPI Aw +h hh Remove statement 4; you no longer need to 
cS1 ¥ know the smallest number. 


“= 


0 


Note: The closing V must not be entered on 
the same line as [A n] ; you must enter it on 
another line or an error will occur. 


¥SOTATEQAV —— Display the modified function. 
VO STAT xX 


m4 Ne oX . 
2 J X 
37) C+/K + x ~————— Displayed function—the original line 4 was 
| [xX deleted and the statements were renumbered. 
ol (PSX SX 

V 

STAT 2 9 1 

eo 
\. 
9? 
8 


You can also delete a statement by displaying the statement on input 
line 1, pressing the ATTN key (to blank the entire expression), and then 
pressing EXECUTE. Displaying a specific statement is discussed next. 
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Displaying a Specific Statement or from a Specific Statement to the 
End of a Function 


You have already seen how to display the entire function; you can also 
display only one statement or each statement from a certain statement 
to the end of the function. To display one statement, you enter [nq], 
where n is the statement number you want to display. To display each 
statement from a certain statement to the end of the function, you 
enter [[In] , where each statement from statement n to the end of the 
function is to be displayed. 


EXAMPLE: 


¥STATL SLI V¥+——— Display statement 3. 
cs) “carn teax 


VSTATEU4 TY +—— Display each statement from statement 4 to 
ry “XxX the end of the function. 
eae CT /X) | 7X 


Modifying a Single Statement 


You can correct keying errors in a statement of a function the same way 
you correct keying errors made during entering of instructions in 
execution mode. That is, the same procedures for inserting, deleting, or 
replacing characters are used. To correct keying errors in function 
definition mode, you must currently be entering the statement in error 
or you must display the statement you want to correct. 


EXAMPLE: 


¥YSTATE 24 Open the function and display statement 2. 
C27 x 


C27 N ~~ Enter an N to replace the X in the displayed line. 
caa s¥ (You now want to know the number of elements 


The 5110 responds with [3] ; now enter the closing ¥. 


¥STATE 11 ¥ +——— Display the function. 


¥ STAT X 
cad Ne pX 
eae N 
3c C+/X) + ox ~—— N has replaced the X. 
My 2] p/x 
on “CP /X) EL /X 
v 
STAT 2 9 4 
3 
rr 
y 
8 


Editing the Function Header 


You can edit the function header the same way you would edit any 
other statement in the function. To do this, you specify statement O as 
the statement to be edited. 


EXAMPLE: 


VOTATLOISTATL xX V+— The original function header is 


VSTATALTIAY replaced with this function header. 
V STATI X Es 
ee Ne oX 


12 Display the function. 
2d N 
Ls C+/X) SOK Note: Do not be concerned at this 
oe Pex time if the error message SI 
coo CT SX) -L LX DAMAGE is displayed; this error 
¥ message and a suggested user response 


is described in the /BM 5770 APL 
Reference Manual, SA21-9303. 


YSTATECOIV You cannot display the function 
TEFN ERROR STAT because the function no 
YSTAT longer has that name. 
rN 
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A Faster Way to Add, Replace or Insert One Statement in a Function 


If your function is closed and you have only one statement to add, 
replace, or insert, you can do it using only one instruction. For 
example, the following instruction opens, changes, and closes the 


function definition: 


Opens the STAT1 function. 
Specifies that statement 3 is to be edited. 
Replaces the existing statement 3. 


Closes the STAT1 function. 


VOTATILATC+HS XO ENV 


EXAMPLE: 


VSTATICOIVY 
WV STATI Xx 

Cid | Ne px 

c2] oN 

CST C+#/X) +X 

Cea PyX 

CSI CP / XL 7X 
V 


Display the STAT1 function. 


VSTATICGI'° THIS STATEMENT WAS ADEN '? 


Add a statement to the function. 


STATI 2 9 | ———_______ Now try the function. 
3 
If. 
y 
& 
THIS STATEMENT WAS AED 


YSTATILS1¢0+/X) +NV-—Replace a statement. 
Oe a ea ee 
YSTATIEQIY Insert a statement. 


V STATI xX i ee 
Pid Ne ox 


Pie] N 

PS C4 /X 0 +N 

Cy 2 17% 

CS PX 

C4 CP LX 4k 

red “THIS STATEMENT WAS ANDET 
¥ 


Display the modified function. 


oOrAaTi 2 9 J 


tM 


ty. 
tl 
=) 


% 


3 
THIS STATEMENT WAS ATIMHET 


nw 
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TYPES OF FUNCTION HEADERS 


Like the APL built-in functions, you can have user-defined functions 
with one or two arguments. You can also have user-defined functions 
without any arguments. The number of arguments required by a 
function is defined in the function header. For example: 


vy RESULT<ARGUMENT1 FUNCTIONNAME ARGUMENT2 
aes function requires two arguments. 


vV RESULT<FUNCTIONNAME ARGUMENT 


N 


This function requires one argument. 
vy RESULT<FUNCTIONNAME 


we function requires no argument. 


When a function is executed, the value used for an argument is assigned 
to the variable name that appears as the argument in the function 
header. This variable is then used in the function. For example, you 
might have the following function: 


¥VREea DIVITK & 
Pid Reatkyv 


If you enter 10 DIVIDE 2, the value 10 is assigned to A and the value 2 
is assigned to B. Now when the statement A: B is executed, the result 
is 5, 


Note: For some user-defined functions (as with some built-in functions), 


it is important that you enter the arguments in the proper order. For 


example, if you enter 2 DIVIDE 10, the answer would be 0.2 instead of 5. 


When you define a function with one argument, the argument must be 
to the right of the function name; otherwise, the argument will be 
treated as the function name, and vice versa. 


EXAMPLES: 


VReA AREAL K~—— Two arguments-—this function finds 
Lid Re AxRY the area of a rectangle. 

L2 AREAL 12 
Tuy 


¥RESQRT X +——————— One argument-—this function finds 
Cid Rexe OV the square root of a number. 

Atl WY 9 16 25 34 

SQRT & ——_—————_ The argument can be a vector. 
L234 5 6 


VReOTCE ————————__ No argument-—this function simulates 
La Rees 4 the roll of two dice. 
ed V 
NICE 


1 The results can be any pair of numbers 
NICE ae between 1 and 6. 
3 


WHY HAVE A RESULT VARIABLE? 


So far in our discussion of user-defined functions, we have usually 
defined functions with a result variable. A result variable is a variable in 
which the result of a function is temporarily stored for use in an APL 
expression. When your function has a result variable, it is said to have 
an explicit result. Without an explicit result, your function cannot be 
used in an APL expression. 


The following function has a result variable; therefore, it has an explicit 
result. 


Result Variable 


VRESULTe@TY ITEMX CO OT 
Pid RESULTECOSTSATY ¥ 


Result Variable 


The result variable must appear in both the function header and the body 
of the function (it must be included in the statement where the final 
result is determined). 
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EXAMPLES: 


VaTY ITEM COST ——\ Define a function without an 
Cig COsST+aTyy explicit result. 
10 ITEM .60 


STORE¢1O ITEM .60 The result of the function cannot 


0,06 be used in APL expressions. 


VALUE ERROR 
STORE¢10 ITEM 0.4 
A 


10410 TTEM . 40 


0,04 
VALUE ERROR 
LO4#10 ITEM 0.6 


VRESULTe&@ LTEMY C——\— Define a function with an explicit 


Lid RESULTEeC+aQ¥ result. 

LO ITEMY . 46 
i. 0¢ 

STORE¢ 10 TTEMY . 40 The result of the function can now 

STORE be used in an APL expression. 
0,06 

10410 ITEMY . 60 Remember, if you pian to use the 

La, 08 


function you are defining in an APL 
expression, you must provide a 
result variable. 


LOCAL AND GLOBAL NAMES 


A name appearing in a user-defined function can be either /oca/ or 
global. A global name has the same value during the execution ofa 
function as it has outside of the function. A local name has a value that 
is available only while the function is active. Any name appearing in the 
function header (except the function name) is a local name. So far we 
have seen that a function header can contain a result variable and argu- 
ments. Because these variable names are contained in the function 
header, they are local to the function. But other names can also be 
made local to the function if they are placed in the function header 
following the right argument (if any) with a semicolon preceding each 
name. For example, the function header V LOOP R;1;J makes the right 
argument R and the variables | and J local to the function. Now to see 
how local and global names work, let’s use some. 


EXAMPLES: 


VALUE ERROR 


VALUE ERROR 


VGLOBAL ————_—_—_——_————_ Define a function without 


GAS any local names. 
(308 & 4 
GCeS 
GA+GB+EC¥ 
GLOBAL 
GA 
Gk Because these names are global 
variables, they also exist out- 
GC side the function. 


¥YLOCAL ;lA;LR; LOC ——— Define a function with all 
ee tN i 


1a tye A local names. 
1a RS & ly. | 
Lt@e& Notice how the names are 
LAtLB+L OV made local to the function. 
LOCAL 
Execute LOCAL, then enter the variable 


names to see what values they represent. 


Le 


LA 


“A 


LK 


Because these variable names are 
local to the function, they repre- 
sent a value only during the 
execution of the function. 


Lk 


“ 


LC 


VALUE ERROR 


i 
2d 
C3] 


Cu 


ak 


igo Define a function using both 
A local (GA and GB) and global 
(GC) names. 


YCOMBINATION; GA; GE 
GAES —— Local names that are the same 
Ghee? as existing global names. 
GleS eee 
GA+GR+ OC 


COMBINATION 


Global name. 


(4 
Notice that outside the function, 
GE the existing global values (previously 
established by the function GLOBAL) 
Gt are used. The new values (6 and 7) 


existed only during the execution of 
the function. 


Because this variable name is not 


local to the function, the global 
value was changed. 
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Now, you are probably wondering why you should make variable names 
local to a function. Following are some reasons for using local variables: 


e Let's assume you have defined a function named COUNT that uses a 
variable named X. At some later time, you assign the result of an 
important calculation to a global variable named X. Now if you 
execute COUNT, the following conditions can occur: 


1. If X was made local to COUNT, the global value of X is not 
changed. 


2. | X was not local to COUNT, the global value of X (the 
results of your important calculation) is changed. 


e You can conserve space in your active workspace by not storing the 
values for variables you do not use outside a function. 


BRANCHING, LABELS, AND LOOPING 


Branching and Labels 


Statements in a user-defined function are normally executed in the order 
indicated by the statement numbers, and execution terminates at the end 
of the last statement in the sequence. However, this normal order of 
execution can be modified by branching (transferring to another point 

in the sequence). Branching is indicated by a right arrow + followed by 
a label that specifies the statement to be branched to. 


For example, the expression >START means branch to a statement 
labeled START. When a label is assigned to a statement, the label is 
followed by a colon and must precede the statement. The colon separates 
the label from the statement: 


C20 START: NéeN+). 


CS 8 START 


In the previous illustration, the label START is assigned to the second 
statement in the function. In this case, START has a value of 2; however, 
if the function is edited and the statement is no longer the second 
statement in the function, START will automatically be given the value 
of the new statement number. Now as the function executes, when 
statement 5 is executed, a branch is taken to the statement labeled 
START. If the same label appears more than once in a function, any 
branches taken to that label always branch to the first statement with 

the label. 


Labels are local to a function; that is, they can be used only within that 
function. Following are some rules that apply exclusively to the use of 
labels: 


@ They must not appear in the function header. 
e You cannot assign values to them. 


There are two types of branch statements you can use—unconditional 
branches and conditional branches: 


e Unconditional branches are branches that are taken each time the 
branch statement is executed. You have already seen an example of 
an unconditional branch, [5] +START, where the branch to the 
statement labeled START is taken each time statement 5 is executed. 
Another common use of an unconditional branch is +0, which causes 
the execution of the function to be terminated. 


® Conditional branches are branches that are taken depending upon 
some condition that exists at the time the branch statement is executed. 
Conditional branches are used, for example, to branch to a statement 
if a condition is true and to otherwise continue with the next 
statement (fall through). This type of branch can be entered like 
this: 


+(CONDITION)/N 


The branch to statement N is taken if the condition is true; otherwise 
the next statement is executed. For example, APL executes the 
branch statement +(I=N)/START as follows: 


1. First, the condition (1>N) is evaluated; the result is 1 if the 
condition is true and 0 if the condition is false. 


2. The result of step 1 is then used as the left argument for the 
compress (/) function: 

a. If the result of step 1 was 1, START is selected from the right 
argument and a branch to the statement labeled START is 
taken. 

b. If the result of step 1 was 0, nothing is selected from the right 
argument (an empty vector is the result). A branch to an 
empty vector means execute the next statement in sequence 
(fall through). 
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In the following example, you will use two variations of a function to 
determine the sum of each number from 1 to the value of the argument 
(each function will use a different method of branching). 


EXAMPLES: 


VS¢SUM2 N 
Ria Sea 
Lead fed 
rel) CHECK :3CL=N)/0+—— Branch to 0 (terminate the function) or fall 
Ku Ses+i through to the next statement. 
csp Tered 
réd e¢CHECK YY ——————- Unconditional branch to CHECK. 
SUM2 S 


VYSe SUMS ON 

Rid Seo 

bad Led 

ES. GHECK.Seot] 

mH Te T+ 

pS] 39 TEN) /CHECK ¥+——— Branch to CHECK or fall through. 
SUMA S 


Is 


Looping 


A repeated segment of a function is called a loop; when you have a loop 
in. your program, you must provide a way to get out of the loop. 


-EXAMPLE: 


. ¥l.00QP -—_—_——————__—_—__ This function executes a 
Cia Tea continuous loop. 
C2 LABEL: ‘THIS PROGRAM CONTAINS A LOOP’ 
CS] Tere 
CH SLABRELY 
LOOP 
LOOP 


THIS PROGRAM CONTAINS &A 
THIS PROGRAM CONTAINS A LOOP 
THIS PROGRAM CONTAINS A LOOP 
THIS PROGRAM CONTAINS A LOOP 
THIS PROGRAM CONTAINS A LOOP 
THIS PROGRAM CONTAINS A LOOP Note: To stop execution 
THIS PROGRAM CONTAINS A LOOP of LOOP, press the ATTN 


key. 


L.OQP £3 3—_—_—_  —— The name of the function 
and the statement number 


where execution stopped is 
displayed. 


VLOOP EY + CTs) LABEL V+-—\— Provide a way to get out of 


YLOOPEGQIY the loop. 
M4 Te G Display the function. 
an | LABEL: “THIS PROGRAM CONTAINS A LOOP’ 
I 3 Te Ted. 
Se $073) /LABREL 
\! 
LOOP 


THIS PROGRAM CONTAINS & LOOP 
THIS PROGRAM CONTAINS Aa LOOP The loop is executed three 


THIS PROGRAM CONTAINS A LOOP times. 
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HOW TO ENTER DATA DURING FUNCTION EXECUTION 
bi 2 


So far you have defined functions for which you have supplied the data 
for the function as arguments. This method of supplying data limits you 
to two input arguments, and you must be familiar with the function so 
that you can enter the required arguments in the correct order. However, 
you can also define user-defined functions that display requests for input 
data as the function executes. This type of function allows you to input 
any amount of data; and you can also define your function so that it 
specifies what type of data is to be entered. To do this, you use the 

1) (quad) or [| (quad quote) symbols in your function to request input 
from the keyboard. When‘a [J is encountered in a function, execution 
stops and [J: is displayed to indicate that the system is waiting for 
numeric or character input (character data must be enclosed in single 
quotes) from the keyboard. Whena [ is encountered in a function, 
execution stops, the cursor appears, and the system waits for input from 
the keyboard; but in this case, everything on the input line from position 
1 to the cursor or the last character entered (whichever is the farthest on 
the input line) is treated as character input, even though you do not use 
enclosing single quotes when you enter the data. 


EXAMPLE: 


Enter the following user-defined function to determine the final score of a 
baseball game: 


VYRASE BALL 
"ENTER THE NAME OF THE VISTTING TEAM’ 
Be ae 
"ENTER THETR SCORE BY INNING’ The input from the 
keyboard will replace 
the [J or ["] and be 
assigned to the 
variables. 


| 

1 VWSCORE ¢(] —_—_———————_ 

|} CENTER THE NAME OF THE HOME 
4 HOME eb 

| 

U 

} 


TEAM ' 


"ENTER THETR SCORE BY TNNING’ 
Coke 


J o' THE FINAL SCORE Wat: 


L007 VIS 
Lid +/V¥ SCORE 
L290 HOME 
Lad +/HSCORE¥ 
The score by inningwas: REDS -—~ 010203 2 5 0 
BLUES ~-0 00231300 


EXAMPLE (continued) 


~ Now execute the function: 


Notice how the messages 
BASEBALL board input required. 


ENTER THE NAME OF THE VISITING TEAM 
~ REDS Om i — — this character data is not 
enclosed in single quotes 
because it was requested 


ENTER THEIR SCORE BY INNING by a ['] in the function. 
bl 

, od02 0% 2 5 )-_———_——— This is not character data 
ENTER THE NAME OF THE HOME TEAM because it was requested by a 
BLUES [] and is not enclosed in 
ENTER THETR SCORE BY INNING single quotes. 
[1 : 

Oe UO a A a: GE Note: A(]: indicates that 
THE FING SCORE WAS: the keyboard input is reques- 
RET ted by [] in the function; no 
13 (1: (blank line) indicates : 
BLUES that the keyboard input is! 
9 requested by [] in the 
function. 


When you are using interactive functions, there may be times when you 
need to escape from a request for input. Normally, pressing the ATTN 
key causes the execution of your function to stop; however, pressing the 
ATTN key during a request for input does not stop the function (the 
function continues to wait for input to be entered). Therefore, APL 
provides a way to escape from input requests. To escape from a [] input 
request, you enter >, which causes execution of your function to be 
terminated. 


To escape from a [ input request, you must enter the DW (OUT) character. 
You enter this character by holding the CMD key and pressing the 


+ 


key once, and then pressing the EXECUTE key. This will cause the 
execution of your function to stop. What you can do next when your 
function stops is discussed next, in Chapter 8. 
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EXAMPLE: 


ASE BALL, A eehefFh eh Letts use the BASEBALL 


ENTER THE NAME OF THE VISITING TEAM function to show how to 
RETIS escape from input requests. 
ENTER THEIR SCORE BY INNING 

a 3+ 0000s = — Entering + in response to 


a [] input request causes the 
execution of the function 


BASEBALL to be terminated. 
ENTER THE NAME OF THE VISITING TEAM 
(ooo ee lllmeee Try escaping from a I} by 


entering >. Your entry was 
treated as a character, and 
used as the visiting team’s 


ENTER THEIR SCORE BY INNING name. 
[l: 

14daddiitiswre— Enter some numbers so that 
ENTER YHE NAME OF THE HOME TEAM the next [] input request 


will be displayed. 


{ 
INTERRUPT eee ae 
BASEBALL 467 HOME ¢E — Entering the DU character 

A (holding CMD and pressing 


the key once) causes 
+ 


the execution of the function 
to stop. 


Chapter 8. What You Can Do When Your Function Stops 


The execution of your user-defined function will stop when: 

e The ATTN key is pressed. 

e The stop feature is used. 

e An error is encountered in the function. 

e A Ucharacter (the CMD key held and the key pressed once) 
| is entered for a [] input request. 

A function that has stopped executing for one of the preceding reasons 
is called a suspended function. A suspended function is still active, since 


its execution can be resumed later. 


Now let's look at what you can do when your function stops executing. 


WHEN THE ATTENTION KEY IS PRESSED 
When you press the ATTN key during the execution of your user- 
defined function, the function stops executing at the end of the state- 
ment currently being executed. In this case, the 5110 displays the 
function name and the next statement number to be executed. 
After your function stops executing, you can do one of the following: 
e Edit the function. 


e Execute the function again. 


e Execute another user-defined function. 


Execute system commands except for )SAVE, )COPY, and )PCOPY. 
The system commands are described in the /BM 5110 APL Reference 
Manual, SA21-9303. 


Terminate the function by entering >. 
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Generally, after you have stopped your function by pressing the ATTN 
key, you will want to resume execution of the function at a later time. 
To do this, you enter +[] LC. [] LC is a system variable that contains the 
statement number of the next statement to be executed (see the /BM 
5110 APL Reference Manual, SA21-9303 for a complete description of 
the £] LC system variable). 


Note: |f you want to resume execution at a statement other than the 
one immediately following the last statement executed, enter >n (where 
n is the statement number at which you want to resume execution). 


EXAMPLES: 


ad 


VSFUNCTION; COUNT —_— 


COUNT é 0 


I 2 J 
M3 
Ch oI 
C3 


6 


>1.00P 


COUNT 


ed 


THIS 
THIS 
THIS 
THIS 
THIS 
THIS 
THIS 


SFUNC TION 32 


“TIMES *¥ 


SFUNCT LON 


FUNCTION 
FUNC YT TON 
FUNC TION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCT TON 


CONTAINS 
CONTAINS 
CONTAINS 
CONTAINS 
CONTAINS 
CONTAINS 
CONTAING 


"THIS FUNCTION LOOPED 


LOOP 
LOOP 
LOOP 
LOOP 
LOOP 
LOOP 
LOOP 


LOOP: "THIS FUNCTION CONTAINS A LOOP’ 
COUNT ¢ COUNT +4. 


VSFUNC TION I CCOUNT = 3) “LOOPY 


TLC 


iti 


ie 


ee 


Define a function 
with a continuous 
loop. 


Press the ATTN 
key to stop execution 
of the function. 


The function is 
suspended at the 
statement number 
shown in the [ ] on 
your display screen. 


Edit the function so 
that it does not 
contain a continuous 
loop. 


Resume execution 
of the function. 


EXAMPLES—continued 


THIS FUNCTION LOOPED 
7 The value shown 


TIMES here on your display 
screen is the number 
of times the function 
looped. 


SFUNCT LON A SCNow execute the 


THIS FUNCTION CONTAINS A LOOP function again. 
THES FUNCTION CONTAINS A LOOP 
THIS FUNETION CONTAINS A LOOP 


THIS FUNCTION LOOPED 
me) 
TIMES 


Note: When the shift key is held down and the ATTN key is pressed 
during the execution of an APL statement or expression (either within 
or outside a user-defined function), the execution of the statement or 
expression stops immediately. The message INTERRUPT, the statement 
being processed, and the caret (A) that indicates where the statement 
was interrupted is displayed. You can use this method to interrupt 
statements that take a long time to execute. However, any results 
generated by the statement or expression before it was interrupted 
might not exist after the interrupt. 


WHEN THE STOP FEATURE IS USED 


You are already familiar with the stop feature, which was discussed in 
Chapter 7. When using the stop feature (as when using the ATTN key), 
you can do the following: 


e@ Edit the function. 

e Execute the function again. 

e Execute another user-defined function. 

e Execute system commands except for SAVE, )COPY, and )PCOPY. 
e Resume function execution by entering > [] LC. 


@ Terminate the function by entering —. 
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WHEN AN ERROR IS ENCOUNTERED IN THE FUNCTION 


The reason the execution of your function stopped in this case, unlike 
the reasons in the other two cases, cannot be controlled by you. That 
is, the 5110 automatically stops the execution of your function and 
displays an error message when an error occurs in the function. The 
error messages and a suggested user’s response for each error are 
described in the /BM 5170 APL Reference Manual, SA21-9303. 


Errors in a user-defined function are sometimes difficult to find and 
correct. The error message displayed indicates where the execution of 
the statement stopped, and why; but the reason the failure occurred at 
that point might have been because a mistake (either a keying error or 

an error in the solution to the problem) was made earlier in the statement 
or because a mistake was made in an even earlier statement in the 
function. Following are some hints to help you find errors in a statement 
or expression that is failing or giving the wrong results. 


e Check the expression (statement) you entered for any keying errors. 


e Analyze the execution of the expression from right to left. Remember, 
APL executes an expression from right to left with the expressions in 
parentheses resolved (right to left) as they are encountered. 


e Use the shape p function to make sure the shapes of the arguments 
are what you expect. For example, suppose you have a function 
named CAT that catenates two vectors together to form one vector; 
however, one of the arguments you supplied was a matrix (this 
causes a LENGTH ERROR). 


e Enter the names to check the values of the arguments to make sure 
they are what you expect (local variables in a suspended function 
can be displayed, since the function is still active). 


e Break the expression down and execute it in smaller segments. 
Theup @@ and down a | arrows (scroll up and scroll down 


keys) make it easy for you to break the expression down; that is, 
you can execute the expression as APL does (from right to left with 
expressions in parentheses resolved as they are encountered). To do 
this, you enter the first operation performed by APL, for which the 
result will be displayed. Then press the down arrow three times and 
the up arrow once to remove the previous result from the display 
screen (so that it is not on the input line when the EXECUTE key 

is pressed again) and to place the instruction you just entered in a 
position for you to add more operations. Now you can add the next 
operation to the instruction, and the next, until the error in the 
instruction is found. 


e Display intermediate results from the expression using the 0 . This 
does not change the final result. For example: 


Ry Up ge ey D 


BxT Cus [esi 2 


It is important that you maintain a history (either a printout on the 
printer or a handwritten copy) of what you did when you were trying 
to find the cause of an error. Then if you cannot find the error and you 
think the problem is caused by the 5110, this history will help your 
service representative determine where the problem is. 


When a function has stopped because an error occurred, as when pressing 
the ATTN key or using the stop feature, you can do the following: 


e Edit the function. 

@ Execute the function again. 

e Execute another user-defined function. 

e Execute system commands except for SAVE, )COPY, and )PCOPY. 
e Resume execution of the function by entering +{]LC. 


e Terminate the function by entering >. 


WHEN A UCHARACTER IS ENTERED FOR A (y INPUT REQUEST 


In Chapter 7, you used the 0 character to escape from a ["] input request 
and to stop function execution. In that case, the 5110 displayed the 
message INTERRUPT, the function name, and the statement that 
requested the input. After your function stops, you can do the same 
operations that you did when the function stopped for any other reason. 
However, in most cases, you will want to terminate the function by 
entering >. 


FINDING OUT WHAT FUNCTIONS ARE SUSPENDED 


The state indicator contains the function name and the number of the 
statement to be executed next for each suspended function. To display 
the state indicator, you enter )SI or )SINL. See the /BM 57110 APL 
Reference Manual, SA21-9303, for more information on the state 
indicator. 
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USING THE HOLD KEY TO STOP PROCESSING 


We have already discussed the ways a user-defined function can be 
suspended. You can also stop the execution of a function by pressing the 
HOLD key once. In fact, this stops the entire system from processing 

any data. To resume processing after pressing the HOLD key, you must 
press the HOLD key again. The HOLD key is useful when the information 
on the display screen is changing rapidly; that is, you can stop processing, 
read the displayed information, and then resume processing. 


EXAMPLES: 


VHOL TIF ———_—————— Define a function. 
Cid Hea 
C27 “PRESS THE HOLE KEY TO STOP PROCESSING’ 
E30 LOOP: HeHed 
oe | 
CS 32 CHK 25) SLOOPY 


HOLL. OF 
PRESS THE HOLD KEY TO STOP PROCESSING 
I 
2 
4) Thee value displayed here on your 
display screen indicates how many 


times the function looped before 
processing stopped. 

Notice that the characters HOLD 
are displayed in the bottom left 
corner of the display screen when 
the HOLD key is pressed once. 


HOLA O 


Now press the HOLD key again to resume processing. 
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Chapter 9. Using Tape or Diskette Storage (Your Library) 


So far you have used only the 5110 active workspace. The active work- 
space is the part of the 5110's internal storage where the calculations 
are performed; it is also the place where the variables and user-defined 
functions are stored. When you set the 5110 POWER ON/OFF switch 
to OFF or press RESTART, the data in the active workspace is lost. 
However, before turning the power off or pressing RESTART, you can 
save the data in your active workspace by writing the contents of the 
active workspace on a tape cartridge or diskette. This media (tape or 
diskette) is like a library; that is, you can write the contents of your 
active workspace on the media (like placing a book on the library shelf) 
and, at a later time, put the information stored on the media back into 
the active workspace (like taking the book off the library shelf to use 

it again). 


The library consists of one or more files (each file is like a book), and 
just as each book in the library has a name, each file that contains 
information on the media also can have a name (file identification). 


The IBM 5110 system commands are your means of controlling the 
active workspace and storage media (library). Look at the labels above 
the alphameric keyboard; you can enter these system command key- 
words by simply pressing the CMD key with the appropriate key below 
the label. The system command keywords can also be entered character 
by character. Notice that each system command begins with a ) symbol. 
There are some system commands that do not appear on the labels 
above the keyboard. All of the 5110 system commands are discussed 

in detail in the /BM 5110 APL Reference Manual, SA21-9303. 


In the following example, you will see how some of the system com- 
mands work. First, a tape cartridge or diskette must be inserted into 
your system. 

If you are using a tape cartridge: 

1. Be sure the tape contains no data required for any further use. 


2. Make sure that the SAFE switch (Figure 3) does not point to SAFE. 


3. Insert the tape cartridge (Figure 4). 
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If you are using a diskette: 


1. 


3. 


Be sure the diskette is initialized and contains no data required for 
any further use. 


Note: The IBM-supplied diskettes are initialized before they are 
sent to a customer. 


Remove the diskette from the protective envelope (Figure 5). 


Insert the diskette into diskette drive 1 (Figure 6). 


Make sure the SAFE switch 


is in this position. 


Figure 3. The SAFE Switch 


Insert the tape cartridge as shown. 


Figure 4. Inserting a Tape Cartridge 
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Figure 5. Removing the Diskette from the Protective Envelope 


ite 


——. 


ATMA 


fo- 


This label must be in 
the lower right corner 
as the diskette is 
inserted. 


Figure 6. Inserting a Diskette in Diskette Drive 1 


EXAMPLES: 


Press RESTART on your 5110; all the data that was in the active workspace is now 
lost. 


CLEAR WS ————___—_—_———___—__ J}, message will be displayed 
when the 5110 is again ready 
for you to enter data. 


Enter the following function and variable so that you can store them on the media 
for later use: 


VEXAMPLE ; Rj NAME 
Cid ‘THIS FUNCTION COUNTS THE CHARACTERS IN YOUR NAME’ 
C2] ‘NOW ENTER YOUR NAME‘ 
C3] NAME¢O 
C4 ‘THERE ARE’ 
CS ep. NAME 
[6] “CHARACTERS IN YOUR NAME'Y 


VARTABLE¢ 'LET''S SAVE THIS DATA’ 


Now try the function EXAMPLE to see if it works. 


JFNS The )FNS system command 
EXAMPLE displays user-defined function 
names in the active workspace. 


IVARS The )VARS system command 
VARTABLE displays the global variable 
names in the active workspace. 


Before the storage media can be used, the files you want to use must be formatted. 
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The )MARK command formats 
files on the media. This com- 
mand specifies: 

— — Size of the files to be 


formatted 
— — Number of files to format 
| — — Starting file number 
| So Device. If you are using 
IMARK 16 3 1 1 tape storage, specify 1 
MARKED 0003 00146 (tape drive 1). However, 


if you are using diskette 
storage, specify 11 (disk- 
ette drive 1) instead of 
tape drive 1. See the 
IBM 5110 APL Reference 
Manual for the default 
device used by the system 
if the device is not 
specified. 


APL will respond with MARKED, 
number of the last file marked, 
and the size of the files. If the 
file you want to use has been 
marked before, you will get a 
message ALREADY MARKED. 
In this case, enter GO and press 
the EXECUTE key to reformat 
the tape files. 


Note: \f you enter the )MARK command by holding down the CMD key and pressing 
the key, the command is displayed as follows: 
0 


IMARK KE NF SF DEV -These characters identify the 

SV parameters required for the 
command and must be replaced 
with the required information. 
KB stands for the size of the files 
to be formatted in K(1024) byte 
blocks; NF stands for the number 
of files to be marked; SF stands 
for the starting file number; DEV 
stands for the device number the 
media is on. 


After the )MARK command is executed, the files are formatted in blocks of 1024 bytes. 
For example, the size of the files just formatted is sixteen 1024-byte blocks (or 16,384 
total bytes). See the /BM 5110 APL User’s Guide, SA21-9302, for information on 

what size to format files. 


Now let’s write the contents of the active workspace on the media. In the following 
examples, if you are using diskette storage, specify device 11 (diskette drive 1) instead 
of device 1 (tape drive 1). For example, device/file number 1001 should be 11001 for 
diskette. 


ICONTINUE 1001 TNF O~—This becomes the name of the 
CONTINUED 1001 INFO file on tape. 


This specifies the device/file 
number (device 1, file 001) 
to which the contents of the 
active workspace are written. 


BD 2 | See oe ee do not have to turn the 
CLEAR WS power off or press RESTART 
to clear all of the existing data 
out of the active workspace; 
you can use this sytem 
command. 


The data in a stored workspace can be placed back into the active workspace. 


oo FOAM L001 _ TNFO—~—_____ the stored warkepace Gatie 
LOADED 1001 TNEO iworkspace 1D). 


‘The device/file number from 
which the stored workspace 
will be loaded. 
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FNS 
EXAMPLE a Now the data that was stored 
VARS on the media is in the active 


VARTABLE workspace once again. 


The remaining system commands are described in the /BM 5770 APL Reference 
Manual. Try using these system commands to see how they work. 


So far, you have learned how to write the entire contents of the active 
workspace on the media. However, you can also write one variable at a 
time to a file on the media. This data can then be read from the media 

at a later time in the same order as it was written to the media. For 

more information on how to do this, see the /BM 5770 APL User’s Guide. 


WHAT ARE SYSTEM VARIABLES? 


System variables are variables within the active workspace that control 
the system. All system variables begin with the [] symbol and are set to 
an initial value by the 5110 in a clear workspace. See the /BM 5770 
APL Reference Manual for a complete description of each system 
variable. In the following example, you will see how the value of some 
system variables can be changed and how this affects certain APL 
functions. 


EXAMPLES: 


The index origin [JIO system variable determines the index origin. The value of 

the []IO system variable can be either 0 or 1, which means that the first element of 

a vector or array is indexed with a 0 or 1 depending upon what the []!O system 

variable is set to. The APL functions 1 ? 4 Y¥ and indexing ([]) are affected by the 
[] 10 system variable. 


gro —_——_————_ You can display the value of a 
system variable the same way you 
display the value of any variable. 


The []10 system variable is 
initially set to 1 by the system. 


Results when the []IO system 
variable is set to 1. 


573 


3 1 2 These numbers can be in any 


Wiaed order. 
04] 2 3 4 You can change the value of 


33 some system variables. 


Notice how the results of these 
APL functions change when the 
[]!O system variable is changed. 


These numbers can be in any 
order. Notice that the values 
start from 0. 


The printing precision []PP system variable determines the number of significant 
digits displayed. 


LPP 
se sssesesessSsSCSTihte [JPP system variable is 
be initially set to 5 by the system. 
0.33333 
fPPe2 
i3 Five significant digits are 
O43 displayed. 


Now only two significant digits 
are displayed. 


The comparison tolerance []CT system variable determines how close two numbers 
must be when you are using the relational. floor, or ceiling functions. 


CT ————_—-—+_—_________—- The [CT system variable is 


LE WAS initially set to 1E 13 by the 


LIS So Lhd Pia eae Ro as" 
. 


‘ ws ved od oe] wd wd Cer, Jf i] a a) A @) + sy stem a 
0 , 
CTE Le TS These two values are not 


OS SSR" el Pa mS he 


Adio ay ede che considered equal. 
‘1 ae 
Now these two values are 


considered equal. 
CLEAR The workspace is clear and the 
ee eae eee 


CLEAR WS system variables are once again 
set to their original values. 
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REMEMBER, APL IS A GOOD LANGUAGE 
TO EXPERIMENT WITH. THE MORE YOU 


EXPERIMENT, THE MORE YOU LEARN. 
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Appendix A. Overstruck Characters 


Using Using the CMD 
These Key and Pressing 
Name Character Keys This Key 


Comment A 
Cc 
Compress # (See note) 
Execute ® 
B 
Expand . (See note) 
U 
Factorial, Combination ! (-} 
Format 5 T 
N 
Grade Down V v 
G 
Grade Up A an 
ii 
Logarithm ® 
P 
Matrix Division Bl _ 
F 
Nand ‘A 
Nor Vv 


<2 


Protected Function 
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Using Using the CMD 
These Key and Pressing 


Name Character Keys This Key 


Quad Quote " 
Rotate, Reverse ) 

‘Rotate, Reverse e (See note) 
Transpose 0) 


Note: These are variations of the symbols for these functions; they 
are used when the function is to act on the first coordinate of an array. 
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JCLEAR command 112, 115 
JCONTINUE command 1 12 
)FNS command 111 

YLOAD command 112 
JMARK command 112 
)VARS command 111 


[1] 48, 49, 51 
{o) «81 
[On] =86 
[n{]] 86 
[An] 85 

f] 98 

[]: 98 

LIC 115 
{WO 114 
f|PP 39,115 
"| 98 


>[]LC 79, 102 
Wecharacter 99, 105 
Vsymbol 74 
[function 32,44 
| function 32, 45 
A function 33 

V function 33 

? function 34, 46 
1 function 25, 35 
o function 35 

< function 37 
<function 37 

> function 37 
>function 37 
=function 37 

# function 37 

A function 40, 41 
v function 40,42 
/function 47,48 
,function 50 

@ function 54 


active workspace 107 
adding statements 82 
addition 17 
alphakeys 2 
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alphameric keys 2 
ALREADY MARKED 112 
alternating sum 59 

and function A 40, 41 

and reduction 51 

APL language 1 


APL system command keywords 


arguments 17, 31,90 
arithmetic function keys 4 
arithmetic operations 17 
assign avalue 20 
assignment arrow 20 


attention key (see ATTN key) 


ATTN key 4, 14,77, 101 
average 56 


backspace key 4, 10, 11, 12 


BASIC/APL switch 4 
black background 9 

black characters 9 

blank character 29 
branching 94 

brightness control 9 
built-in functions 1, 17, 62 


calculator arrangement 4 
catenate function, 50 
ceiling function [ 32 
character data 29 
CLEARWS 4 

closing V 75 

CMD key 4, 11 

column 25 

command keywords 4 
comparison tolerance [| |CT 
compress function / 47 
conditional branch 95 
conform 51 

consecutive numbers 34 
control panel 1 
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coordinate, acted on 48, 49 
correct a keying error 13 
correcting keying errors 10 
cursor 7 


deal function? 46 

default device 112 

del symbol 74 

delete acharacter 11 

deleting statements 85 

diskette 107, 108, 110 

diskette drive 110 

display appearance 9 

display global variable names 111 
display registers/normal switch 4 
display screen 1,7 

displayed information 7,8 

displaying astatement 86, 87 
displaying data 7 

displaying from a specific statement 86 
displaying the entire function 81 
displays user-defined function names 111 
division 17 

down arrow 9, 14,75 


editing a function 80 

editing the function header 87 
empty vector 35, 53 

entering data 7 

entering data during function execution 98 
equal to function = 37 

error in the function 104 
error message 21,77, 104 
escape from input requests 99 
EXECUTE key 4,8, 14 
execution mode 74 

expand a vector or matrix 48 
expand function \ 48 

explicit result 91 


features 1 

files 107 

flashing line 7 
floor function | 32 
format files 112 


forward space key 4, 10, 11, 12 
function body 75 

function definition 74 

function definition mode 74 
function editing 80 

function execution stops 101 
function header 74, 87, 91,92 
functions 1 


global names 92 

global variable names 111 

grade down function Y 33 

grade up function 4 33 

greater than function > 37 
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workspace 112 

plus reduction 56 

portable computer 1 
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stop execution 78 
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stop processing 106 
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